Server API

Server

Require MrDialogue from a server Script to create dialogues, register handlers, and start sessions.

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local MrDialogue = require(ReplicatedStorage.Packages.MrDialogue.Server)

The explicit .Server entry point preserves complete Luau types. Requiring the package root remains supported as an untyped compatibility shortcut.

Release information

MrDialogue.Version -- "1.0.0"
MrDialogue.ProtocolVersion -- 1
MrDialogue.Limits -- frozen table of protocol and definition bounds

MrDialogue

MrDialogue.new

MrDialogue.new(definition: DialogueDefinition): Dialogue

Validates a dialogue definition and returns an immutable Dialogue.

The definition is deep-copied before it is stored. Mutating the original table after this call does not alter the dialogue.

Throws when: the definition is malformed, a transition points to a missing node, a speaker or emotion is unknown, or a field has the wrong type.

Handlers referenced by conditions and actions do not need to be registered until the dialogue is started.

Source

MrDialogue.RegisterCondition

MrDialogue.RegisterCondition(
    name: string,
    handler: (context: DialogueContext, ...any) -> boolean
): ()

Registers a global condition handler. Names must be non-empty and unique. Handlers must return a boolean without yielding. A handler that throws, yields, or returns another type fails closed and produces a warning.

MrDialogue.RegisterCondition("hasCoins", function(context, amount)
    return context.data.coins >= amount
end)

Source

MrDialogue.RegisterAction

MrDialogue.RegisterAction(
    name: string,
    handler: (context: DialogueContext, ...any) -> ...any
): ()

Registers a global action handler. Names must be non-empty and unique. Actions are synchronous and may return:

Return	Meaning
no values	Success
true	Success
false, details?	Failure

Throwing, yielding, returning an invalid value, or explicitly failing cancels the session with reason action_error.

Source

Dialogue

Created by MrDialogue.new.

Dialogue.Id

Dialogue.Id: string

Read only

The ID from definition.id.

Dialogue:Start

Dialogue:Start(
    player: Player,
    options: SessionOptions?
): (Session?, string?)

Starts an independent session for player.

local session, startError = dialogue:Start(player, {
    npc = workspace.Guide,
    timeoutSeconds = 120,
    data = {
        questId = "find_the_map",
    },
})

if not session then
    warn(startError)
end

When the request is valid but cannot start, it returns nil and a message:

Message	Cause
player is not connected	The player has left Players.
player dialogue client is not ready	MrDialogue.Start() has not initialized on that client yet.
player already has an active dialogue session	A player can have only one active session.
... is not registered	A referenced condition or action handler is missing.

Invalid argument types throw instead of returning an error message.

timeoutSeconds is an inactivity timeout reset after each accepted client response. It defaults to 120 and may be configured up to 3600. A timed-out session is cancelled with reason timeout.

Note

A graph that resolves immediately to an end node still returns a Session, but it is already inactive. Because it never opened a client presentation, the adapter receives neither OnShow nor OnEnd; inspect the server outcome directly.

Source

Session

A session represents one player's run through a dialogue.

Properties

Session.Player: Player
Session.DialogueId: string
Session.Ended: RBXScriptSignal

Read only

Session:IsActive

Session:IsActive(): boolean

Returns true while the dialogue is accepting progress from the client.

Session:GetOutcome

Session:GetOutcome(): SessionOutcome?

Returns nil while active, then the final completed or cancelled outcome.

local outcome = session:GetOutcome()
if outcome and outcome.status == "completed" then
    print(outcome.result)
end

Session.Ended

Fires once with the frozen SessionOutcome when an active session completes or is cancelled:

session.Ended:Connect(function(outcome)
    print(outcome.status, outcome.result or outcome.reason)
end)

An immediately terminal session can finish before a listener is connected; always check GetOutcome() once after Dialogue:Start().

Session:Cancel

Session:Cancel(reason: string?): boolean

Cancels an active session. Returns true if this call ended the session and false if it had already ended.

The default reason is manual. Custom reasons must be namespaced, for example quest:abandoned or npc:despawned.

Source