Getting Started

Overview & Core Setup

Dialog script containers allow you to define native Paper API UI screens rendered on the client side.

Anatomy of a Script

Structure
my_dialog:
    type: dialog
    base:
        type: multi
        title: <gold>Header Title
    bodies: ...
    inputs: ...
    buttons: ...

Universal Base Properties

typeRequired
The layout engine: multi, list, confirm, or notice.
titleRequired
The main header. Supports tags and MiniMessage.
external titleOptional
The window title in the client's OS frame.
can close with escapeOptional
Boolean. If true (default), ESC closes the window.
Layout Types

Multi (Form)

A versatile form layout. Supports multiple inputs and custom buttons.

Multi-specific `base:` Properties

columnsOptional
Integer. Arrange elements into grid columns.
exit buttonOptional
A button definition block used as a dedicated close button.

Multi-specific Root Properties

buttons:Required
A map of action buttons at the bottom.
Layout Types

List (Menu Grid)

Designed to display buttons that open other dialog scripts.

List-specific `base:` Properties

columnsOptional
Integer. Columns in the grid.
button widthOptional
Integer. Sets a fixed pixel width for auto-generated buttons.

List-specific Root Properties

dialogs:Required
A list of script names to display.
Layout Types

Confirm (Yes/No)

A simple confirmation box with two actions.

Confirm-specific Root Properties

yes:Root
Affirmative ActionButton definition.
no:Root
Negative ActionButton definition.
Layout Types

Notice (Popup)

A simple alert box.

Notice-specific Root Properties

button:Root
Optional ActionButton definition. If omitted, creates a default "OK" button.
Components

Inputs

Inputs defined under inputs:. Values available via <context.key_name>.

Text Input (type: text)

width
Field width.
max length
Limit characters.
initial
Default text.
label visible
Boolean. Show/Hide the label.
multiline options
Section with max lines and height.

Boolean Input (type: boolean)

initial
Default state (true/false).
on true / on false
Labels for ON/OFF states.

Number Input (type: number)

start / endReq
Range bounds (Float).
step
Increment step.
initial
Starting value.
width
Slider width.
label format
Format string (e.g. "Val: %s").

Single Choice (type: single)

options:Req
Map of options (id, display, initial).
label visible
Boolean.
Components

Visual Bodies

Defined under bodies: root key.

type: message
• message: The text.
• width: Fixed width.
type: item
• item: ItemTag.
• width / height: Visual size.
• show tooltip / decorations: Booleans.
• description: Nested message-type body.
Components

Buttons & Actions

Common properties and action types.

labelReq
Button text.
tooltip
Hover text.
width
Button width.

Action Types (type:)

SCRIPT
Key: script:. Runs Denizen commands.
RUN_COMMAND
Key: command:. Runs a player command. Must include slash (/).
OPEN_URL
Key: url:. Opens a link.
COPY_TO_CLIPBOARD
Key: text:. Copies text.
Reference

Full Example

staff_application.dsc 
st:
    type: dialog
    base:
        type: multi
        title: <yellow>Staff Application
        columns: 1
    bodies:
        header:
            type: message
            message: <gray>Please fill out the form below carefully.
    inputs:
        1:
            type: text
            label: Your Real Name
            key: applicant_name
        2:
            type: number
            label: Your Age
            start: 13
            end: 99
            initial: 18
            step: 1
            key: applicant_age
        has_experience:
            type: boolean
            label: Previous Experience?
    buttons:
        1:
            label: <green>Submit Application
            script:
            - narrate "Name: <context.applicant_name>"
            - narrate "Age: <context.applicant_age>"
            - narrate "Experience: <context.has_experience>"
        2:
            type: OPEN_URL
            label: Join Support Discord
            url: https://discord.gg/example
Preview