GD Resources logo
GitHub

Adding Dialog #

OmgRod avatar
Written by:
OmgRod
Owner

The Dialog API allows you to trigger Geometry Dash's native cutscene dialogue system directly from your Lua scripts. When a dialogue opens, player movement is automatically paused until the dialogue sequence finishes.

Basic Usage #

To present a dialogue sequence, pass an array of speech frames to Dialog.show().

lua
1-- Example: Shop entry dialogue sequence
2Dialog.show({
3    {
4        speaker = "Scratch",
5        text = "Hello player!",
6        avatar = 8,
7        scale = 1.0,
8        unskippable = false
9    },
10    {
11        speaker = "Scratch",
12        text = "Goodbye player!",
13        avatar = 9
14    }
15}, {
16    bgType = 2,
17    animateSide = true
18})

API Reference #

Dialog.show(dialogList, [options]) #

Displays a sequence of interactive dialogue boxes.

Arguments #

  1. dialogList (table): An array table where each element is a table containing the setup for an individual dialogue box.
  2. options (table, optional): A configuration table controlling overall dialogue presentation.

Dialogue Entry Options #

Each dialogue object in the dialogList array supports the following properties:

Dialogue Entry Options
ParameterTypeDefaultDescription
speakerstring""The name displayed at the top of the dialogue box.
textstring""The text content to display. Supports GD dialogue tags (e.g., <d030>, <cr>).
avatarinteger1The character avatar/portrait frame ID to render.
scalenumber1.0Text scale inside the dialogue box.
unskippablebooleanfalseIf set to true, the player cannot tap/click to skip this line immediately.
colortable{255, 255, 255}An array containing RGB values {R, G, B} (0–255) to tint the main text.

Global Presentation Options #

The optional second argument table controls how the dialogue UI layers into the scene:

Global Presentation Options
ParameterTypeDefaultDescription
bgTypeinteger2Background style for the dialogue layer (e.g., standard, darkened overlay).
animateSidebooleantrueWhen true, slides the dialogue box in randomly from either side of the screen upon opening.

Text Formatting Tags #

Geometry Dash uses built-in text tags within dialogue strings to trigger color shifts, speed adjustments, and sound effects:

  • Text Speed: <d030> changes text delay (e.g., 030 = 0.30s per letter).
  • Color Tags: <cr> (Red), <cg> (Green), <cb> (Blue), <cy> (Yellow), <co> (Orange), <c#HEX> (Custom Hex Color).
  • Reset Color: </c> resets text color back to default white.
  • Sound Effects: <s100> plays a specific GD sfx ID when that word appears. </s> stops/resets current text sound settings.
Edit this page