Skip to Content
defold-typescript libraries
Insality

Insality/defold-printer/printer

A symbol-by-symbol text writer for Defold Engine. Developed for rich game dialogs.

  • GitHub: Insality/defold-printer — pinned to 1.2.2
    1. Pick a release from Insality/defold-printer 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 printer from "printer.printer"

Functions

new(self: unknown, template_name: string): Printer

Creates a printer instance on a gui scene that holds a printer template. The module reads the template's prefab, prefab_icon and text_parent nodes, and places text from the top left of text_parent.

Parameters

  • self: unknown — The gui script's self.
  • template_name: string — The name of the printer template in the gui scene.

Returns

  • Printer

print(self: Printer, str: string, source?: string): boolean

Starts printing text on an instance. Wrap a style name in braces to switch style ({red}), use {/} to return to the default style, {n} for a line break and {image:name} for an image.

Parameters

  • self: Printer — The printer instance, created by new.
  • str: string — The text to print.
  • source?: string — A source added with add_source_style. Its style is copied over the default style and becomes this text's base style, which {/} returns to.

Returns

  • boolean — true when the new text starts printing; false when text was still printing, so the new text did not start. print then calls instant_appear, which reveals that text at once only when the effective style of the symbol currently appearing has can_skip set to true; otherwise it keeps printing.

instant_appear(self: Printer)

Makes every symbol of the current text visible at once, only when the effective style of the symbol currently appearing has can_skip set to true; otherwise the text keeps printing.

Parameters

  • self: Printer — The printer instance, created by new.

fadeout(self: Printer)

Stops printing and fades every symbol of the current text out over 0.3 seconds.

Parameters

  • self: Printer — The printer instance, created by new.

clear(self: Printer)

Deletes all of the current printed text.

Parameters

  • self: Printer — The printer instance, created by new.

update(self: Printer, dt: number)

Advances printing and the text shake. Call it from the gui script's update.

Parameters

  • self: Printer — The printer instance, created by new.
  • dt: number — The dt of the gui script's update.

final(self: Printer)

Deletes the printed text and stops printing. Call it from the gui script's final.

Parameters

  • self: Printer — The printer instance, created by new.

play_sound(name: string)

Called whenever a symbol with a style sound appears; it does nothing until a project replaces it with its own sound playback. A namespace import is read-only, so assign through a cast that keeps the function free of self: (printer as { play_sound: (this: void, name: string) => void }).play_sound = (name) => { ... }.

Parameters

  • name: string — The sound of the symbol's style.

add_styles(styles_new: Record<string, PrinterStyle>)

Adds styles to the module, shared by every instance. A style with an existing name replaces it, and a style named default replaces the default style.

Parameters

  • styles_new: Record<string, PrinterStyle> — The styles, keyed by style name.

add_source_style(source: string, style: string)

Adds a source style: a print given this source copies the style over the default style and uses it as the text's base style.

Parameters

  • source: string — The source name to pass to print.
  • style: string — The style name.

add_word_style(word: string, style: string)

Adds a word style: every occurrence of the word in printed text is wrapped in the style, then returns to the default style. The match is case sensitive.

Parameters

  • word: string — The text to style.
  • style: string — The style name.

Variables

printers: LuaTable

A table the module creates and never reads.

Types

Printer

Printer.print(str: string, source?: string): boolean

Starts printing text. Wrap a style name in braces to switch style ({red}), use {/} to return to the default style, {n} for a line break and {image:name} for an image.

Parameters

  • str: string — The text to print.
  • source?: string — A source added with add_source_style. Its style is copied over the default style and becomes this text's base style, which {/} returns to.

Returns

  • boolean — true when the new text starts printing; false when text was still printing, so the new text did not start. print then calls instant_appear, which reveals that text at once only when the effective style of the symbol currently appearing has can_skip set to true; otherwise it keeps printing.

Printer.instant_appear()

Makes every symbol of the current text visible at once, only when the effective style of the symbol currently appearing has can_skip set to true; otherwise the text keeps printing.

Printer.fadeout()

Stops printing and fades every symbol of the current text out over 0.3 seconds.

Printer.clear()

Deletes all of the current printed text.

Printer.update(dt: number)

Advances printing and the text shake. Call it from the gui script's update.

Parameters

  • dt: number — The dt of the gui script's update.

Printer.final()

Deletes the printed text and stops printing. Call it from the gui script's final.

Printer.is_print?: boolean

Whether the printer is printing text now. It is unset until the first print, fadeout or final.

PrinterStyle

PrinterStyle.font_height?: number

In pixels, the height of every symbol or image. It also sets where a new line starts.

PrinterStyle.spacing?: number

In pixels, the horizontal distance between symbols.

PrinterStyle.scale?: number

The scale of every symbol.

PrinterStyle.speed?: number

In seconds, the time between printing one symbol and the next.

PrinterStyle.appear?: number

In seconds, how long a symbol takes to fade in from alpha 0 to 1.

PrinterStyle.shaking?: number

In pixels, how far every symbol in this style shakes. 0 disables it.

PrinterStyle.shake_on_write?: number

In pixels, how far the whole text shakes when a symbol in this style appears. 0 disables it.

PrinterStyle.color?: string

The hex color code of every symbol in this style, for example "#CACACA".

PrinterStyle.waving?: boolean

true makes the symbols wave up and down.

PrinterStyle.can_skip?: boolean

true lets instant_appear reveal text in this style at once. The default style sets it, so a style that omits it inherits it; a replacement default style that omits it disables instant_appear.

PrinterStyle.sound?: string | false

The sound name passed to play_sound when a symbol appears, or false for none.

On this page