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- Pick a release from Insality/defold-printer releases and add its Source code (zip) URL (or a packaged
.zipasset, if the library ships one) togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as printer from "printer.printer"
- Pick a release from Insality/defold-printer releases and add its Source code (zip) URL (or a packaged
Functions
new(self: unknown, template_name: string):Printerprint(self:Printer, str: string, source?: string): booleaninstant_appear(self:Printer)fadeout(self:Printer)clear(self:Printer)update(self:Printer, dt: number)final(self:Printer)play_sound(name: string)add_styles(styles_new: Record<string,PrinterStyle>)add_source_style(source: string, style: string)add_word_style(word: string, style: string)
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'sself.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 bynew.str:string— The text to print.source?:string— A source added withadd_source_style. Its style is copied over the default style and becomes this text's base style, which{/}returns to.
Returns
boolean—truewhen the new text starts printing;falsewhen text was still printing, so the new text did not start.printthen callsinstant_appear, which reveals that text at once only when the effective style of the symbol currently appearing hascan_skipset totrue; 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 bynew.
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 bynew.
clear(self: Printer)
Deletes all of the current printed text.
Parameters
self:Printer— The printer instance, created bynew.
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 bynew.dt:number— Thedtof the gui script'supdate.
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 bynew.
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— Thesoundof 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 toprint.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 withadd_source_style. Its style is copied over the default style and becomes this text's base style, which{/}returns to.
Returns
boolean—truewhen the new text starts printing;falsewhen text was still printing, so the new text did not start.printthen callsinstant_appear, which reveals that text at once only when the effective style of the symbol currently appearing hascan_skipset totrue; 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— Thedtof the gui script'supdate.
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.