{"id":15722554,"url":"https://github.com/whiteboxdev/library-defold-typewriter","last_synced_at":"2025-06-10T19:35:16.975Z","repository":{"id":64170810,"uuid":"562570105","full_name":"whiteboxdev/library-defold-typewriter","owner":"whiteboxdev","description":"Defold Typewriter provides text scrolling and styling in a Defold game engine project.","archived":false,"fork":false,"pushed_at":"2024-05-24T16:19:57.000Z","size":216,"stargazers_count":28,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-15T06:16:15.563Z","etag":null,"topics":["defold","defold-library"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"zlib","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/whiteboxdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-06T18:49:37.000Z","updated_at":"2025-04-09T14:12:00.000Z","dependencies_parsed_at":"2024-04-19T22:34:54.048Z","dependency_job_id":"4cf7c149-06e2-471e-bd2a-f4b4fb5b0fc5","html_url":"https://github.com/whiteboxdev/library-defold-typewriter","commit_stats":null,"previous_names":["whiteboxdev/library-defold-typewriter"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-typewriter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-typewriter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-typewriter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-typewriter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/whiteboxdev","download_url":"https://codeload.github.com/whiteboxdev/library-defold-typewriter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249016643,"owners_count":21198833,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["defold","defold-library"],"created_at":"2024-10-03T22:08:22.547Z","updated_at":"2025-04-15T06:16:21.175Z","avatar_url":"https://github.com/whiteboxdev.png","language":"Lua","funding_links":[],"categories":["Libraries"],"sub_categories":["Programming Language"],"readme":"# Defold Typewriter\n\nDefold Typewriter provides text scrolling and styling in a Defold game engine project.\n\nPlease click the ☆ button on GitHub if this repository is useful or interesting. Thank you!\n\n![alt text](https://github.com/whiteboxdev/library-defold-typewriter/blob/main/assets/thumbnail.png?raw=true)\n\n## Installation\n\nAdd the latest version to your project's dependencies:  \nhttps://github.com/whiteboxdev/library-defold-typewriter/archive/main.zip\n\n## Configuration\n\nImport the dtypewriter module into your gui script like so:\n\n```\nlocal dtypewriter = require \"dtypewriter.dtypewriter\"\n```\n\nInitialize dtypewriter with `dtypewriter.init()`. This function requires several metrics to properly align text content inside a textbox. The following image outlines what each parameter refers to:\n\n![alt text](https://github.com/whiteboxdev/library-defold-typewriter/blob/main/assets/metrics.png?raw=true)\n\nThe more interesting parameters are outlined here:\n\n1. `container_node_id`: Each character in a textbox is created as an individual gui node. These nodes are adopted by a parent container node, which defines the origin position of each character.\n2. `text_area_x`: X offset of text content.\n3. `text_area_y`: Y offset of text content.\n4. `text_area_width`: Total width of text content, which dictates the point of line wrap.\n5. `line_count_max`: Number of lines to display in a textbox before beginning a new paragraph.\n6. `line_offset`: Number of spacing pixels between each line.\n\nText input must be parsed and loaded with `dtypewriter.load()` before being displayed with `dtypewriter.start()`. Text input should be formatted similarly to HTML elements. The following describes all element names and supported values:\n\n| Name      | Description                                            | Values                                | Examples                                           |\n|-----------|--------------------------------------------------------|---------------------------------------|----------------------------------------------------|\n| line      | Wrap to next line.                                     | N/A                                   | \\\u003cline\u003e                                            |\n| paragraph | Stop typing and wait, then move onto next paragraph.   | N/A                                   | \\\u003cparagraph\u003e                                       |\n| color     | Set color of next characters.                          | \"default\", string                     | \\\u003ccolor=default\u003e, \\\u003ccolor=green\u003e                   |\n| speed     | Set speed of next characters in characters per second. | \"default\", \"instant\", positive number | \\\u003cspeed=default\u003e, \\\u003cspeed=instant\u003e, \\\u003cspeed=30\u003e    |\n\nThe example animation was created by passing the following string into `dtypewriter.load()`:\n\n```\n\"Just like the classic RPG dialog systems, \u003ccolor=green\u003edtypewriter\u003ccolor=default\u003e is a fantastic dialog solution!\u003cparagraph\u003eIt can do all kinds of neat things, like \u003ccolor=green\u003ecolors\u003ccolor=default\u003e, \u003cspeed=3\u003espeeds\u003cspeed=default\u003e, and \u003cspeed=instant\u003einstant text display\u003cspeed=default\u003e, among other things!\"\n```\n\nInstead of changing the alpha of each character from 0 to 255 instantly, a smoother and more gradual fade can be enabled with `dtypewriter.set_fade_delay()`. The default fade value is 0.\n\nWhen a new paragraph is needed to continue displaying characters within the predefined textbox, characters will stop being typed and dtypewriter will wait until `dtypewriter.continue()` is called.\n\nThe programmer will receive a message in their `on_message()` function on significant state changes, such as waiting for a new paragraph or typing a character. See the [API: Properties](https://github.com/whiteboxdev/library-defold-typewriter#dtypewritermessages) section for more information.\n\nOnce the loaded text is done being typed, the programmer should call `dtypewriter.clear()` to clear internal tracking variables and free dynamically allocated resources.\n\n## API: Properties\n\n### dtypewriter.messages\n\nTable of messages that are passed to the `on_message()` function of your gui script.\n\n```\ndtypewriter.messages =\n{\n    start = hash(\"start\"),\n    restart = hash(\"restart\"),\n    type = hash(\"type\"),\n    wait = hash(\"wait\"),\n    continue = hash(\"continue\"),\n    complete = hash(\"complete\"),\n    clear = hash(\"clear\")\n}\n```\n\n1. `start`: Loaded text is starting to be typed.\n2. `restart`: Typing is restarted from the beginning.\n3. `type`: An individual character is typed.\n4. `wait`: No more characters can be typed within the boundaries of the textbox and a new paragraph must be started.\n5. `continue`: A new paragraph is started.\n6. `complete`: Loaded text is done being typed.\n7. `clear`: Text is unloaded and resources are freed.\n\n## API: Functions\n\n### dtypewriter.init(container_node_id, font_id, text_area_x, text_area_y, text_area_width, line_count_max, line_offset, messages_url)\n\nInitialize dtypewriter. If dtypewriter was already initialized, call `dtypewriter.clear()` before reinitializing.\n\n#### Parameters\n\n1. `container_node_id`: Container node that defines the origin position of each character node.\n2. `font_id`: Hashed id of the font to use.\n3. `text_area_x`: X offset of text content.\n4. `text_area_y`: Y offset of text content.\n5. `text_area_width`: Total width of text content.\n6. `line_count_max`: Number of lines before starting a new paragraph.\n7. `line_offset`: Number of spacing pixels between lines.\n8. `message_url`: URL to where [dtypewriter messages](https://github.com/whiteboxdev/library-defold-typewriter#dtypewritermessages) are sent.\n\n---\n\n### dtypewriter.clear()\n\nClear internal tracking variables and free dynamically allocated resources. This function should be called when text is no longer desired on screen, likely after `dtypewriter.messages.complete` is received in the `on_message()` function.\n\n---\n\n### dtypewriter.load(text)\n\nLoad raw text to be parsed into formatted gui text nodes. Calls `dtypewriter.clear()` before performing any other tasks.\n\n#### Parameters\n\n1. `text`: Raw text. See the [Configuration](https://github.com/whiteboxdev/library-defold-typewriter#configuration) section for information on how to insert styling elements.\n\n---\n\n### dtypewriter.start()\n\nStart typing characters after loading text with `dtypewriter.load()`.\n\n---\n\n### dtypewriter.restart()\n\nRestart typing characters after calling `dtypewriter.start()`.\n\n---\n\n### dtypewriter.continue()\n\nContinue onto the next paragraph after the end of a paragraph has been reached.\n\n---\n\n### dtypewriter.skip()\n\nSkip to the end of the current paragraph if characters are being typed.\n\n---\n\n### dtypewriter.add_color(name, color)\n\nAdd a custom color in the `\u003ccolor=[color]\u003e` element. If the color name already exists, it is overwritten.\n\n#### Parameters\n\n1. `name`: Name of the color.\n2. `color`: The color itself `vector4`.\n\n---\n\n### dtypewriter.set_default_color(color)\n\nSet a default color or in the `\u003ccolor=default\u003e` element.\n\n#### Parameters\n\n1. `color`: The color itself `vector4`.\n\n---\n\n### dtypewriter.clear_colors()\n\nClear all custom colors, excluding the default color.\n\n---\n\n### dtypewriter.set_fade_delay(delay)\n\nSet the amount of time it takes for the alpha of an individual character to change from 0 to 255 when it is typed. The default value is 0.\n\n#### Parameters\n\n1. `delay`: Amount of seconds for a character to become completely opaque.\n\n---\n\n### dtypewriter.set_default_type_speed(speed)\n\nSet the default type speed in characters per second in the `\u003cspeed=default\u003e` element.\n\n#### Parameters\n\n1. `speed`: Type speed in characters per second.\n\n---\n\n### dtypewriter.is_clear()\n\nCheck if no text is loaded.\n\n#### Returns\n\nReturns `bool`.\n\n---\n\n### dtypewriter.is_loaded()\n\nCheck if text is loaded with `dtypewriter.load()`.\n\n#### Returns\n\nReturns `bool`.\n\n---\n\n### dtypewriter.is_typing()\n\nCheck if dtypewriter is actively typing.\n\n#### Returns\n\nReturns `bool`.\n\n---\n\n### dtypewriter.is_waiting()\n\nCheck if the end of a paragraph has been reached and dtypewriter is waiting to move onto the next paragraph with `dtypewriter.continue()`.\n\n#### Returns\n\nReturns `bool`.\n\n---\n\n### dtypewriter.is_complete()\n\nCheck if dtypewriter is done typing the loaded text, but has not yet been cleared with `dtypewriter.clear()`.\n\n#### Returns\n\nReturns `bool`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhiteboxdev%2Flibrary-defold-typewriter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhiteboxdev%2Flibrary-defold-typewriter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhiteboxdev%2Flibrary-defold-typewriter/lists"}