Dialogue

💬 TSS Dialogue: A Dynamic Conversation Script

TSS-Dialogue Documentation

Overview

TSS-Dialogue is an immersive NPC dialogue system designed for FiveM RP servers. It enables creators to breathe life into NPCs with dynamic, configurable conversation trees that support conditional visibility, job and gang requirements, and branching outcomes.

This documentation covers the core features, setup, usage, and available exports you can use to extend or integrate the system into your own resources.

---

🔧 Features

• Ped Spawning Anywhere — Client-side export to easily spawn dialogue-enabled NPCs.

• Dialogue System — Supports dynamic trees, conditional options, and text updates.

• Integration Friendly — Works with jim-bridge, inventory systems, targets, menus.

• Highly Configurable — Dialogue text and behaviours are editable through open config files.

---

📦 What's Included

• Drag-and-drop installation

• Multi-framework support (QBCore / custom / standalone)

• Dialogue logic via client-side interaction

• Examples for item/job/gang-based dialogue branching

---

🚀 Usage Example

The /spawntester command spawns a ped with a full dialogue tree:

RegisterCommand("spawntester", function()
    SpawnExamplePed()
end)

You define the ped and its options using the exported spawnNPC function:

local ped = exports['tss-dialogue']:spawnNPC({
    model = 'a_m_m_bevhills_01',
    coords = vector4(x, y, z, heading),
    name = 'Tester NPC',
    NPCText = 'Welcome!',
    targetLabel = "Talk to Big Bill",
    scenario = 'WORLD_HUMAN_DRUG_DEALER',
}, {
    [1] = {
        label = "Who are you?",
        shouldClose = false,
        action = function()
            exports['tss-dialogue']:updateNPCText("I'm a test NPC from TinySprite Scripts.")
        end
    },
    ...
})

You can use conditions like:

• item = 'lockpick'

• job = 'police'

• gang = 'ballas'

• excludegang = 'vagos'

• excludejob = 'garbage'

---

📤 Available Exports

These exports allow you to spawn peds and control dialogues programmatically.

spawnNPC(pedData: table, options: table)

Spawns an NPC with defined behaviour and dialogue.

pedData fields:

• model (string): Ped model name.

• coords (vector4): Spawn coordinates + heading.

• name (string): Display name.

• NPCText (string): Initial text.

• targetLabel (string): Label shown in interaction.

• scenario (string): Optional idle scenario.

• anim (table): Optional anim { name = "dict", dict = "anim" }.

options fields:

Each option contains:

• label (string)

• shouldClose (boolean)

• action (function)

• (optional) item, job, gang, excludegang, excludejob

• canInteract (function): Return true/false to show/hide dynamically

---

updateNPCText(label: string)

Updates the current dialogue text shown in the UI.

exports['tss-dialogue']:updateNPCText("Nice weather today, huh?")

---

changeOptions(label: string, options: table)

Changes the dialogue prompt and replaces the option list.

exports['tss-dialogue']:changeOptions("Wanna hang out?", {
    [1] = {
        label = "Sure!",
        shouldClose = true,
        action = function() end
    },
    [2] = {
        label = "Nah",
        shouldClose = true,
        action = function() end
    }
})

---

🎮 UI Behaviour

• Camera locks to face-to-face view with NPC during dialogue.

• NUI opens with focused interaction.

• UI auto-closes if player walks too far from the NPC.

---

⚠️ Escrow Notes

Some files (like client/main.lua) are escrow protected. However:

• All configs and dialogue content are open.

• The system is fully customisable via exports and editable files.

---

🧠 Best Practices

• Use canInteract for dynamic option visibility.

• Keep dialogue short and engaging.

• Label interactions clearly with targetLabel.

• Use scenarios or animations to give NPCs idle behaviour.

---

🧪 Debugging

Use print statements or a debug logger like:

debugPrint("Something happened")

To help identify state and logic in your dialogue trees.

---

📘 Credits

TSS-Dialogue by TinySprite Scripts. Designed to bring immersive, living worlds to FiveM roleplay servers.

"Breathing life into your RP world with immersive systems that make every interaction count."