Functions Explained

There are several classes included in pdDialogue:

• pdDialogue: used for simple textboxes and has a handful of text utilities
• pdDialogueBox: used for full control over style and dialogue behaviour
• pdPortraitDialogueBox: the same as pdDialogueBox, but with a portrait
• pdDialogueSprite: used to draw a dialogue box as a sprite

If you want a simple introduction to these classes, then check out the Quick Start wiki page. There are more examples in the Examples folder.

pdDialogue

Main User Functions

These functions are the easiest way to use the library.

pdDialogue.say(text, config)

Show a dialogue box with the given text. It handles inputs and automatically closes when the text is finished. It has the following parameters:

• text: the text to display
• config: a table of configuration options (see below)

The function returns the pdDialogue.DialogueBox.

pdDialogue.update()

Updates and draws the current dialogue box created with pdDialogue.say. You should call this in playdate.update.

pdDialogue.setup(config)

Lets you set defaults that the pdDialogue.say dialogue box uses. It uses the same keys as the pdDialogue.set function (see below).

The function returns the previous values of the config.

pdDialogue.set(key, value)

Set a single default value that the pdDialogue.say dialogue box uses. The available keys are in the pdDialogue.DialogueBox_KeyValueMap table, which include the values:

• width
• height
• x
• y
• padding
• font
• fontFamily
• nineSlice
• speed

It also includes the functions:

• drawBackground
• drawText
• drawPrompt
• onOpen
• onPageComplete
• onNextPage
• onDialogueComplete
• onClose

You can read more about these in the pdDialogueBox class. The function returns the previous value of the key.

Utility Functions

These functions are used internally by the library, but can be used by the user to pre-wrap text or to create custom dialogue boxes.

pdDialogue.process(text, width, height, [font])

Given a string of text, width, and height, this function returns an array of wrapped, paginated strings. It has the following parameters:

• text: the text to wrap and paginate
• width: the width in pixels to wrap the text to
• height: the height in pixels to paginate the text to
• font: the font to use when wrapping the text (optional)

pdDialogue.wrap(lines, width, [font])

Given an array of lines, this function returns an array of lines that are wrapped to the given width. It has the following parameters:

• lines: an array of lines to wrap
• width: the width to wrap the lines to
• font: the font to use when wrapping the lines (optional)

The function returns an array of strings.

pdDialogue.window(text, startIndex, height, [font])

Given an array of pre-wrapped strings, this function returns an array of lines that fit within the given height. It has the following parameters:

• text: an array of pre-wrapped strings
• startIndex: the index of the first line to include (can be a float)
• height: the height in pixels to fit the lines within
• font: the font to use calculating text height (optional)

The function returns a single string with newlines.

pdDialogue.paginate(lines, height, [font])

Given an array of pre-wrapped strings, this function returns an array of pages that fit within the given height. It has the following parameters:

• text: an array of pre-wrapped strings
• height: the height in pixels to fit the lines within
• font: the font to use calculating text height (optional)

pdDialogue.getRows(height, [font])

Given a height and font, this function returns the number of rows (floor'd) that can fit within the given height. It has the following parameters:

• height: the height in pixels to fit the lines within
• font: the font to use calculating text height (optional)

pdDialogue.getRowsf(height, font)

Like pdDialogue.getRows, but returns a float.

pdDialogueBox

Class Methods

pdDialogueBox:init([text], width, height, [font])

Create a new instance of pdDialogueBox. It has the following parameters:

• text: the text to display (optional, to leave out pass nil)
• width: the width of the text in pixels (excluding padding)
• height: the height of the text in pixels (excluding padding)
• font: the font to use when displaying the text (optional)

pdDialogueBox:asSprite()

Get the dialogue box instance as a sprite (pdDialogueSprite).

pdDialogueBox:update()

Update the dialogue box. This should be called in playdate.update.

pdDialogueBox:draw(x, y)

Draw the dialogue box at the given position with the top left corner at x, y.

pdDialogueBox:getInputHandlers()

Return a set of input handlers that will control the dialogue box. It should be added to the input stack with playdate.input.pushHandlers. It has the same behavior as Breath of the Wild's dialogue box:

• A: speed up text if incomplete, else advance to the next page or line
• B: skip to the end of the current page, else advance to the next page and skip to end of that line

Want A and B to have the same behavior? Add this somewhere to your code (after you import the library):

function pdDialogueBox:getInputHandlers()
    return {
        AButtonDown = function()
            self:setSpeed(2)
            if self.dialogue_complete then
                self:disable()
            elseif self.line_complete then
                self:nextPage()
            end
        end,
        AButtonUp = function()
            self:setSpeed(0.5)
        end,
        BButtonDown = function()
            self:setSpeed(2)
            if self.dialogue_complete then
                self:disable()
            elseif self.line_complete then
                self:nextPage()
            end
        end,
        BButtonUp = function()
            self:setSpeed(0.5)
        end
    }
end

pdDialogueBox:enable()

pdDialogueBox:disable()

Properties

These should be self-explanatory. The setters should always be used, but in most cases you should be able to use .property to get the value.

pdDialogueBox:setText(text)

Sets the text, wrapping and paginating it, and restarts the dialogue. The text should be a single string. The default implementation uses pdDialogue.process to wrap and paginate the text. Text can be formatted with the playdate's *simple* _markup_, though because of the way the text wrapping works _each_ _word_ _should_ _have_ _its_ _own_ _tags_!

pdDialogueBox:getText()

pdDialogueBox:setPages(pages)

Set the pages for the text and restarts the dialogue.

pdDialogueBox:getPages()

pdDialogueBox:setWidth(width)

pdDialogueBox:getWidth()

pdDialogueBox:setHeight(height)

pdDialogueBox:getHeight()

pdDialogueBox:setPadding(padding)

pdDialogueBox:getPadding()

pdDialogueBox:setFont(font)

pdDialogueBox:getFont()

pdDialogueBox:setNineSlice(nineSlice)

pdDialogueBox:getNineSlice()

pdDialogueBox:setSpeed(speed)

pdDialogueBox:getSpeed()

Overriding Behavior

The drawing functions are passed the x, y position of the top left of the box.

pdDialogueBox:drawBackground(x, y)

Draw the background of the dialogue box at the given position. The default implementation draws a nine slice if set, else draws a white rectangle with black outline.

pdDialogueBox:drawText(x, y, text)

Draw the current text. If self.font is a font family it'll draw with the family, else if self.font is not nil it'll draw the current font, else it uses the current set font.

pdDialogueBox:drawPrompt(x, y)

Draw the "continue" prompt, be default it draws the A button icon.

pdDialogueBox:onOpen()

Called when the dialogue box is opened. Does nothing by default.

pdDialogueBox:onPageComplete()

Called when the dialogue box finishes a page. Does nothing by default.

pdDialogueBox:onNextPage()

Called when the dialogue box moves to the next page. Does nothing by default.

pdDialogueBox:onDialogueComplete()

Called when the dialogue box finishes. Does nothing by default.

pdDialogueBox:onClose()

Called when the dialogue box closes. Does nothing by default.

Utility Functions

pdDialogueBox.buttonPrompt(x, y)

Draw the A button icon at the given position.

pdDialogueBox.arrowPrompt(x, y, [color])

Draw a ▼ symbol at the given position with the color (black if omitted)

pdPortraitDialogueBox

Class Methods

pdPortraitDialogueBox is a subclass of pdDialogueBox and has all the same methods.

pdPortraitDialogueBox:init(name, drawable, [text], width, height, [font])

Create a new instance of pdPortraitDialogueBox. It has the following parameters:

• name: the name of the character
• drawable: the sprite, animation loop, image table, or sprite to use for the character's portrait
• text: the text to display (optional, to leave out pass nil)
• width: the width of the text in pixels (excluding padding)
• height: the height of the text in pixels (excluding padding)
• font: the font to use when displaying the text (optional)

Properties

pdPortraitDialogueBox:setAlignment(alignment)

pdPortraitDialogueBox:getAlignment()

Overriding Behavior

pdPortraitDialogueBox:drawPortrait(x, y)

Draw the portrait for the dialogue box. The default implementation draws a background (either a nine slice or a white rectangle with black outline), then draws the portrait, then draws the name. This is called in pdPortraitDialogueBox:drawBackground.

pdDialogueSprite

pdDialogueSprite:init(dialogue)

Create a sprite that has the dimensions of the provided dialogue box. dialogue parameter must be an instance of or subclass pdDialogueBox.

pdDialogueSprite:add()

Add the sprite so it can be drawn and updated with gfx.sprite.update().

pdDialogueSprite:update()

Update the sprite, called automatically if sprite is added.