> For the complete documentation index, see [llms.txt](https://docs.kojascripts.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kojascripts.eu/new/dialogs/configuration/create-dialog.md).

# Create Dialog

#### 1. Dialog Structure

Each dialog is created using the following function:

```lua
exports['koja-dialogs']:CreateDialog({
    id         = "<unique_dialog_id>",
    npc        = "<npc_model>",
    coords     = vector4(<x>, <y>, <z>, <heading>),
    name       = "<npc_display_name>",
    message    = "<initial_npc_message>",
    tag        = "<display_tag_above_npc>",
    animations = {
        { type = "<animation_type>", dict = "<animation_dict>", anim = "<animation_name>" },
        { type = "<animation_type>", dict = "<animation_dict>", anim = "<animation_name>" }
    },
    actions    = {
        {
            label          = "<button_label>",
            player_message = "<message_player_says>",
            onclick        = {
                message = "<npc_response_after_selection>",
                actions = {
                    { ... }  -- nested actions for more dialogue branches
                },
                open = {
                    window = "<window_type>",   -- "shop", "market" or "crafting"
                    data   = {
                        -- depends on window type
                    }
                }
            },
            close = <boolean>  -- close dialog after clicking?
        },
        -- more actions
    }
})
```

**Fields to highlight:**

* **id** (string): Unique identifier for the dialog.
* **npc** (string): Model name of the NPC (e.g., `"g_m_m_chicold_01"`).
* **coords** (vector4): Position in the world: `vector4(x, y, z, heading)`.
* **name** (string): Display name for the NPC in the dialog header.
* **message** (string): The NPC’s initial message when the dialog opens.
* **tag** (string): A label shown above the NPC (e.g., “Dealer”, “Distributor”, “OG”).
* **animations** (table): List of animation objects:
  * `type` (string): Custom label for the animation (e.g., `"idle"`, `"active"`).
  * `dict` (string): The Animation Dictionary to load.
  * `anim` (string): The Animation Name.
* **actions** (table): Array of player-action objects:
  * `label` (string): Text displayed on the button.
  * `player_message` (string): The player’s dialogue line.
  * `onclick` (table):
    * `message` (string): NPC’s response after clicking.
    * `actions` (table): (Optional) Array of nested actions for further dialogue.
    * `open` (table): (Optional) UI window to open, with:
      * `window` (string): `"shop"`, `"market"`, or `"crafting"`.
      * `data` (table): Data structure depending on the window type.
  * `close` (boolean): Whether to close the dialog after this action.

***

#### 2. Shop Window

The **Shop** window displays a list of items (e.g., weapons) that the player can purchase. Its data block looks like this:

```lua
open = {
    window = "shop",
    data   = {
        products = {
            {
                respname = "<resource_name_in_inventory>",  -- e.g. "weapon_pistol"
                price    = <price_in_game_currency>,        -- e.g. 14250
                label    = "<display_label>",               -- e.g. "Pistol"
                desc     = "<description_text>"             -- e.g. "weapon"
            },
            -- additional products
        }
    }
}

```

Example: Dialog with Shop Window (dealer-1)

```lua
exports['koja-dialogs']:CreateDialog({
    id     = "dealer-1",
    npc    = "g_m_m_chicold_01",
    coords = vector4(492.8855, -1356.6151, 29.3423 - 1, 41.8399),
    name   = "Masked Guy",
    message = "Oi, what are you looking at?",
    tag    = "Dealer",
    animations = {
        { type = "idle",   dict = "rcmjosh1", anim = "idle" },
        { type = "active", dict = "missfbi3_party_d", anim = "stand_talk_loop_a_male1" }
    },
    actions = {
        {
            label          = "Buy Drugs",
            player_message = "I want to buy some drugs",
            onclick        = {
                message = "I'm not selling drugs, I'm selling guns.",
                actions = {
                    {
                        label          = "Ask about guns",
                        player_message = "What guns do you have?",
                        onclick        = {
                            message = "I'll show you now.",
                            open    = {
                                window = "shop",
                                data   = {
                                    products = {
                                        {
                                            respname = "weapon_pistol",
                                            price    = 14250,
                                            label    = "Pistol",
                                            desc     = "weapon"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        label          = "Go away",
                        player_message = "Oh, I think I'll go now...",
                        close          = true
                    }
                }
            },
            close = false
        },
        {
            label          = "Who are you?",
            player_message = "What are you doing here?",
            onclick        = {
                message = "Why do you want to know? Are you from the police?",
                actions = {
                    {
                        label          = "Say no",
                        player_message = "No!",
                        onclick        = {
                            message = "I'll show you now.",
                        }
                    },
                    {
                        label          = "Go away",
                        player_message = "Oh, I think I'll go now...",
                        close          = true
                    }
                }
            },
            close = true
        },
        {
            label          = "Goodbye",
            player_message = "Goodbye!",
            onclick        = {
                message = "Take care!",
                actions = {}
            },
            close = true
        }
    }
})

```

**Notes:**

* Clicking **Buy Drugs** responds that the NPC only sells guns.
* In that branch, **Ask about guns** opens the **Shop** window showing available weapons.
* If **Go away** is chosen, the dialog closes.

#### 3. Market Window

The **Market** window is used for trading resources (e.g., narcotics). Its data structure is identical to **Shop**, but the context is resource exchange:

```lua
open = {
    window = "market",
    data   = {
        products = {
            {
                respname = "<resource_name>",   -- e.g. "packed_weed"
                price    = <price_per_unit>,    -- e.g. 50
                label    = "<display_label>",   -- e.g. "Weed"
                desc     = "<category_description>"  -- e.g. "Narcotics"
            },
            -- additional products
        }
    }
}

```

Example: Dialog with Market Window (dealer-2)

```lua
exports['koja-dialogs']:CreateDialog({
    id     = "dealer-2",
    npc    = "g_m_importexport_01",
    coords = vector4(492.9131, -1461.6570, 29.2863 - 1, 139.3608),
    name   = "Rodrigues",
    message = "Hey you! Come here.",
    tag    = "Distributor",
    animations = {
        { type = "idle_a", dict = "amb@world_human_leaning@male@wall@back@foot_up@idle_a", anim = "idle_a" },
        { type = "active", dict = "missfbi3_party_d", anim = "stand_talk_loop_a_male1" }
    },
    actions = {
        {
            label          = "What Happened?",
            player_message = "Hey, what do you want?",
            onclick        = {
                message = "You sold the dope?",
                actions = {
                    {
                        label          = "Yes",
                        player_message = "Yeah, can I sell it to you?",
                        onclick        = {
                            message = "Right now? All right, give me the dope and I'll give you the cash.",
                            actions = {
                                {
                                    label          = "Give the dope",
                                    player_message = "Here.",
                                    onclick        = {
                                        message = "Yeah, that's it buddy.",
                                        open    = {
                                            window = "market",
                                            data   = {
                                                products = {
                                                    {
                                                        respname = "packed_weed",
                                                        price    = 50,
                                                        label    = "Weed",
                                                        desc     = "Narcotics"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        label          = "No, I'll go do it now!",
                        player_message = "Not yet, please wait!",
                        close          = true
                    }
                }
            },
            close = false
        }
    }
})

```

**Notes:**

* The dialog asks if the player sold the drugs (“You sold the dope?”).
* If **Yes**, **Give the dope** opens the **Market** window for finalizing the transaction.

#### 4. Crafting Window

The **Crafting** window combines raw materials into finished goods. It uses `data.items`, built through `buildRequired()`:

```lua
open = {
    window = "crafting",
    data   = {
        items = exports['koja-dialogs']:buildRequired({
            {
                respname = "<result_item_resource_name>",   -- e.g. "packed_weed"
                label    = "<result_item_label>",           -- e.g. "Packed Weed"
                category = "<item_category>",               -- e.g. "Narcotics"
                required = {
                    { respname = "<ingredient1>", label = "<ingredient1_label>", amount = <quantity1> },
                    { respname = "<ingredient2>", label = "<ingredient2_label>", amount = <quantity2> }
                    -- additional ingredients
                }
            },
            -- additional recipes
        })
    }
}

```

Example: Dialog with Crafting Window (dealer-3)

```lua
exports['koja-dialogs']:CreateDialog({
    id     = "dealer-3",
    npc    = "g_m_m_mexboss_02",
    coords = vector4(466.9149, -1590.3712, 32.8233 - 1, 317.4886),
    name   = "Martin",
    message = "Oh! My favourite worker.",
    tag    = "OG",
    animations = {
        { type = "idle_a", dict = "amb@world_human_leaning@male@wall@back@foot_up@idle_a", anim = "idle_a" },
        { type = "active", dict = "missfbi3_party_d", anim = "stand_talk_loop_a_male1" }
    },
    actions = {
        {
            label          = "Hello!",
            player_message = "Hey Martin, can I pack my weed in your place?",
            onclick        = {
                message = "Sure, come in.",
                actions = {
                    {
                        label          = "Pack weed",
                        player_message = "Yeah, can I sell it to you?",
                        onclick        = {
                            message = "Right now? All right, give me the dope and I'll give you the cash.",
                            actions = {
                                {
                                    label          = "Give the dope",
                                    player_message = "Here.",
                                    onclick        = {
                                        message = "Yeah, that's it buddy.",
                                        open    = {
                                            window = "crafting",
                                            data   = {
                                                items = exports['koja-dialogs']:buildRequired({
                                                    {
                                                        respname = "packed_weed",
                                                        label    = "Packed Weed",
                                                        category = "Narcotics",
                                                        required = {
                                                            { respname = "weed",         label = "Weed",         amount = 5 },
                                                            { respname = "plastic_bag", label = "Plastic Bag",  amount = 1 }
                                                        }
                                                    }
                                                })
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        label          = "I'll come back!",
                        player_message = "Not yet, please wait!",
                        close          = true
                    }
                }
            },
            close = false
        }
    }
})

```

**Notes:**

* Player initiates with **Hello!** asking to pack weed.
* After confirmation, **Pack weed** leads to **Give the dope**, which opens the **Crafting** window.
* `buildRequired()` builds the internal format for recipes.

#### 5. Summary of Fields and Window Differences

| Field / Context            | Shop                                                                               | Market                                                                         | Crafting                                                                                                                                                                  |
| -------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **window**                 | `"shop"`                                                                           | `"market"`                                                                     | `"crafting"`                                                                                                                                                              |
| **Data Structure Key**     | `data.products`                                                                    | `data.products`                                                                | `data.items` (uses `buildRequired`)                                                                                                                                       |
| **Example Product/Recipe** | `{ respname = "weapon_pistol", price = 14250, label = "Pistol", desc = "weapon" }` | `{ respname = "packed_weed", price = 50, label = "Weed", desc = "Narcotics" }` | `{ respname = "packed_weed", label = "Packed Weed", category = "Narcotics", required = { { respname = "weed", amount = 5 }, { respname = "plastic_bag", amount = 1 } } }` |
| **Use Case**               | Buying weapons or other items from an NPC                                          | Selling or buying raw resources (e.g., narcotics)                              |                                                                                                                                                                           |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.kojascripts.eu/new/dialogs/configuration/create-dialog.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.