Skip to Content
defold-typescript libraries
britzldefold-richtext

britzl/defold-richtext/richtext.richtext

Rich-text rendering for Defold: styled spans, embedded tags, and per-color text runs.

  • GitHub: britzl/defold-richtext — pinned to 5.22.1
    1. Pick a release from britzl/defold-richtext releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as richtext from "richtext.richtext"

Functions

create(text: string, font: string, settings?: Settings): LuaMultiReturn<[ Word[], TextMetrics ]>

Creates rich text gui nodes from a text containing markup.

Parameters

  • text: string
  • font: string
  • settings?: Settings

Returns

  • LuaMultiReturn<[ Word[], TextMetrics ]>

tagged(words: Word[], tag: string): Word[]

Get all words with a specific tag.

Parameters

  • words: Word[]
  • tag: string

Returns

  • Word[]

truncate(words: Word[], length: number, options?: { words: boolean; }): Word

Truncate a text down to a specific length. This function has two modes of operation:

  1. It can truncate the text on a per word basis or
  2. on a per character/image basis. The function will disable nodes that shouldn't be visible and in the case of truncating on a per character basis also update the text in nodes that should be partially visible. The text metrics of a truncated word will be updated.

Parameters

  • words: Word[]
  • length: number
  • options?: { words: boolean; }
    • words: boolean

Returns

  • Word

length(text: Word[] | string): number

Get the length of a text ignoring any tags except image and spine tags which are treated as having a length of 1.

Parameters

  • text: Word[] | string

Returns

  • number

characters(word: Word): Word[]

Split a word into it's characters, including the creation of the gui nodes. Each of the characters will be given the same attributes as the word, and they will be positioned correctly within the word.

Parameters

  • word: Word

Returns

  • Word[]

on_click(words: Word[], action: { node_id: Hash; text: string; screen_x: number; screen_y: number; tags: string[]; }): boolean

Call this function when a click/touch has been detected and your text contains words with an a tag. These words act as "hyperlinks" and will generate a message when clicked.

Parameters

  • words: Word[]
  • action: { node_id: Hash; text: string; screen_x: number; screen_y: number; tags: string[]; }
    • node_id: Hash
    • text: string
    • screen_x: number
    • screen_y: number
    • tags: string[]

Returns

  • boolean

remove(words: Word[])

Removes all gui text nodes created by richtext.create().

Parameters

  • words: Word[]

plaintext(words: Word[]): string

Returns the words created by richtext.create() as a plain text string without any formatting or tags. Linebreaks are included in the returned string.

Parameters

  • words: Word[]

Returns

  • string

Variables

ALIGN_LEFT: Alignment

ALIGN_CENTER: Alignment

ALIGN_RIGHT: Alignment

ALIGN_JUSTIFY: Alignment

VALIGN_TOP: VAlignment

VALIGN_MIDDLE: VAlignment

VALIGN_BOTTOM: VAlignment

Types

type Alignment = Hash & Readonly<{ __brand: 'richtext.alignment'; }>

type VAlignment = Hash & Readonly<{ __brand: 'richtext.v.alignment'; }>

FontSettings

FontSettings.regular: Hash

FontSettings.italic: Hash

FontSettings.bold: Hash

FontSettings.bold_italic: Hash

LayersTable

LayersTable.fonts: LuaMap<Hash, Hash>

LayersTable.images: LuaMap<Hash, Hash>

LayersTable.spinescenes: LuaMap<Hash, Hash>

Settings

Settings.width?: number

Settings.position?: Vector3

Settings.size?: number

Settings.parent?: Opaque<"node">

Settings.fonts?: FontsTable

Settings.layers?: LayersTable

Settings.color?: Vector4

Settings.shadow?: Vector4

Settings.outline?: Vector4

Settings.align?: Alignment

Settings.valign?: VAlignment

Settings.line_spacing?: number

Settings.paragraph_spacing?: number

Settings.image_pixel_grid_snap?: boolean

Settings.combine_words?: boolean

Settings.dryrun?: boolean

Word

Word.size: number

Word.color: Vector4

Word.shadow: Vector4

Word.outline: Vector4

Word.node: Opaque<"node">

Word.metrics: { width: number; height: number; total_width: number; max_descent?: number; max_ascent?: number; }

Word.font: string

Word.text: string

TextMetrics

TextMetrics.width: number

TextMetrics.height: number

TextMetrics.char_count: number

TextMetrics.img_count: number

TextMetrics.spine_count: number

On this page

Functionscreate(text: string, font: string, settings?: Settings): LuaMultiReturn<[ Word[], TextMetrics ]>tagged(words: Word[], tag: string): Word[]truncate(words: Word[], length: number, options?: { words: boolean; }): Wordlength(text: Word[] | string): numbercharacters(word: Word): Word[]on_click(words: Word[], action: { node_id: Hash; text: string; screen_x: number; screen_y: number; tags: string[]; }): booleanremove(words: Word[])plaintext(words: Word[]): stringVariablesALIGN_LEFT: AlignmentALIGN_CENTER: AlignmentALIGN_RIGHT: AlignmentALIGN_JUSTIFY: AlignmentVALIGN_TOP: VAlignmentVALIGN_MIDDLE: VAlignmentVALIGN_BOTTOM: VAlignmentTypestype Alignment = Hash & Readonly<{ __brand: 'richtext.alignment'; }>type VAlignment = Hash & Readonly<{ __brand: 'richtext.v.alignment'; }>FontSettingsFontSettings.regular: HashFontSettings.italic: HashFontSettings.bold: HashFontSettings.bold_italic: HashLayersTableLayersTable.fonts: LuaMap<Hash, Hash>LayersTable.images: LuaMap<Hash, Hash>LayersTable.spinescenes: LuaMap<Hash, Hash>SettingsSettings.width?: numberSettings.position?: Vector3Settings.size?: numberSettings.parent?: Opaque<"node">Settings.fonts?: FontsTableSettings.layers?: LayersTableSettings.color?: Vector4Settings.shadow?: Vector4Settings.outline?: Vector4Settings.align?: AlignmentSettings.valign?: VAlignmentSettings.line_spacing?: numberSettings.paragraph_spacing?: numberSettings.image_pixel_grid_snap?: booleanSettings.combine_words?: booleanSettings.dryrun?: booleanWordWord.size: numberWord.color: Vector4Word.shadow: Vector4Word.outline: Vector4Word.node: Opaque<"node">Word.metrics: { width: number; height: number; total_width: number; max_descent?: number; max_ascent?: number; }Word.font: stringWord.text: stringTextMetricsTextMetrics.width: numberTextMetrics.height: numberTextMetrics.char_count: numberTextMetrics.img_count: numberTextMetrics.spine_count: number