{"id":16085568,"url":"https://github.com/Insality/defold-printer","last_synced_at":"2025-10-23T02:30:50.911Z","repository":{"id":45813430,"uuid":"177195893","full_name":"Insality/defold-printer","owner":"Insality","description":"Printer module for rich dialogs in your game","archived":false,"fork":false,"pushed_at":"2024-06-28T22:20:59.000Z","size":1367,"stargazers_count":48,"open_issues_count":5,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-25T07:03:20.261Z","etag":null,"topics":["defold","defold-library","defold-module"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Insality.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"insality","ko_fi":"insality","buy_me_a_coffee":"insality"}},"created_at":"2019-03-22T19:09:15.000Z","updated_at":"2024-11-05T05:59:29.000Z","dependencies_parsed_at":"2024-06-28T23:34:01.041Z","dependency_job_id":"0eb1253c-3323-4486-b81c-05d221dacfaa","html_url":"https://github.com/Insality/defold-printer","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdefold-printer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdefold-printer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdefold-printer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdefold-printer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Insality","download_url":"https://codeload.github.com/Insality/defold-printer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237763855,"owners_count":19362310,"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","defold-module"],"created_at":"2024-10-09T13:02:01.828Z","updated_at":"2025-10-23T02:30:50.905Z","avatar_url":"https://github.com/Insality.png","language":"Lua","readme":"![](docs/logo.png)\n\n[![Github-sponsors](https://img.shields.io/badge/sponsor-30363D?style=for-the-badge\u0026logo=GitHub-Sponsors\u0026logoColor=#EA4AAA)](https://github.com/sponsors/insality) [![Ko-Fi](https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge\u0026logo=ko-fi\u0026logoColor=white)](https://ko-fi.com/insality) [![BuyMeACoffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge\u0026logo=buy-me-a-coffee\u0026logoColor=black)](https://www.buymeacoffee.com/insality)\n\n[![GitHub release (latest by date)](https://img.shields.io/github/v/tag/insality/defold-printer?style=for-the-badge\u0026label=Release)](https://github.com/Insality/defold-printer/tags)\n\n# Printer\nA symbol-by-symbol text writer for Defold Engine. Developed for rich game dialogs.\nSupport UTF-8 symbols (via utf-8.lua). So Russian and other 2+ bytes symbol languages are supported.\n\n# Install\n\nAdd library to dependency:\n`https://github.com/Insality/defold-printer/archive/refs/tags/1.2.1.zip`\n\nIf you use **Defold** version less than `1.7.0` use this version:\n`https://github.com/Insality/defold-printer/archive/refs/tags/1.1.0.zip`\n\n![](docs/example.gif)\n\n# Basic Setup\n\nPlace printer template on you gui scene. Setup font of text and set size of printer background.\n\nText will appearing from top-left of this background. You can setup alpha of this node to see text area.\n\nsetup in gui module:\n```lua\nlocal printer = require \"printer.printer\"\nfunction init(self)\n\tself.printer = printer.new(self, template_name)\nend\nfunction update(self, dt)\n\tself.printer:update(dt)\nend\nfunction final(self)\n\tself.printer:final()\nend\n```\n\nAnd usage will be like this:\n\n```lua\nself.printer:print(\"This is just simple text\")\n```\n\n# Styles\nStyle is lua table with parameters. The default style is the following:\n```lua\ndefault = {\n\tfont_height = 28,\n\tspacing = 1,\n\tscale = 1,\n\twaving = false,\n\tcolor = \"#FFFFFF\",\n\tspeed = 0.05,\n\tappear = 0.01,\n\tshaking = 0,\n\tsound = false,\n\tcan_skip = true,\n\tshake_on_write = 0,\n}\n```\n## Required Default Parameters:\nThese parameters *must* be present in your default or source style.\n- `font_height` in pixels, height of every symbol or image - also used to determine new line position\n- `spacing` in pixels, horizontal distance between symbols\n- `scale` set scale of every symbol to this value\n- `color` hex color code for every symbol the style applies to (ex. \"#CACACA\")\n- `speed` in seconds, the time between each symbol printing\n- `appear` in seconds, the speed of a symbol fading in via gui.animate from alpha 0 -\u003e 1\n- `shaking` in pixels, the amount to shake every symbol the style applies to.\n\n## Other Parameters:\n- `can_skip` if false, printer.instant_appear is disabled while text with this style appears\n- `sound` string. Name of the sound played when a symbol appears. TO-DO: Need to rewrite printer.play_sound function.\n- `waving` set true to enable waving symbol effect\n- `shake_on_write` when true, shake all text symbols when any symbol begins appearing\n\n## Style usage\nTo setup your styles, use `printer.add_styles( {styles} )`. Styles is array of lua tables with style parameters. We will refer to any key of this array as a 'stylename'.\n\nAll new printed text uses the *default* style initially. To change it, enclose a stylename with `{` and `}` before the affected text.\n`{my_style}This is styled text`\n\nUse `{/}` to stop using the previously specified style. Example:\n`{my_style}This is styled text. {/}But this no`\n\nUse `{n}` to add a line break. Example:\n`This row on first line.{n}This line on second line`\n\nYou can mix many styles in one row. Example:\n`{Illidan_name}Illidan{/}: you are {red}not {waving}prepared{/}!`\nIn the above example, for the word 'prepared' - any styles from `{red}` that also exist in `{waving}` will be overwritten by `{waving}`. However, parameters in `{red}` that do not exist in `{waving}` will not be affected. The style exit `{/}` removes the effects of all styles.\n\n# Advanced Setup\n\n## Dialog skip and next\nTo handle next behavior, like to appear all text if it printing, or go to next text if it already showed, you can use something like this on touch event:\n```lua\nif self.printer.is_print then\n\tself.printer:instant_appear()\nelse\n\tself.index = self.index + 1\n\tif self.index \u003c= #self.texts then\n\t\tself.printer:print(self.texts[self.index])\n\tend\nend\n```\n\n\n## Source predefined styles\nSet up a source style to override the default style with a different style for a specific print call.\nFor example, set up the source:\n`printer.add_source_style(\"bob\", \"bob_style\")`\nAnd specify the source in the print call:\n`printer:print(\"Any text you want\", \"bob\")`\nAnytime the *default* style would be used, *bob_style* will be used instead.\n\n## Word styles\nYou can predefine styles for specific strings.\nFor example, set up a word style:\n`printer.add_word_style(\"powerful\", \"cool_style\")`\nNow, providing the following text to a print call:\n`The Defold is amazing, powerful engine`\nwill print as if you provided:\n`The Defold is amazing, {cool_style}powerful{/} engine`\n\nImportant points about word styles:\n- *The 'word' (really it is just a string) is case sensitive. You can use it for coloring characters' names in your game.*\n- *The word style will extend default style of current text, including source style overrides.*\n- *Word styles function by modifying your original print string to include style tags, and inserts the style exit `{/}` at the end.*\n\n## Image usage\nInsert images in your text using `{image:name}` syntax.\nIt will place an image node and call `gui.play_flipbook(node, name)` to it.\nExample:\n`printer:print(\"Lets trade this for 500 {image:coins}!)`\n\n## Multiple instancing\nCreate multiple printer instances with `printer.new()`, using different templates.\n\n## Usage examples\n```lua\nself.printer:print(\"This is {red}test with red style\")\nself.printer:print(\"This is {amazing}multi-{blue}styled text\")\nself.printer:print(\"This is text with{n}new line. And image here {image:coins}\")\nself.printer:print(\"This is {red}red text and {/}return to default\")\nself.printer:print(\"This is with source to use another default style\", \"Illidan\")\n```\n\n# API\n\n## printer.new(self, prefab_name)\nCreate new printer instance to use it for print text\n### PARAMETERS\n- `self` gui self context\n- `prefab_name` printer template name of gui scene\n\n## printer.print(instance, text, [source]\nStart printing text on selected instance\n### PARAMETERS\n- `instance` printer instance, created by *printer.new*\n- `text` string, text to start printing\n- `source` string, name of source to setup other default style for this text\n\n## printer.is_print\nBoolean value to check, if printer now printing text or not\n\n## printer.fadeout\n\n## printer.instant_appear(instance)\nMake all nodes for the current text visible immediately.\n### PARAMETERS\n- `instance` printer instance, created by *printer.new*\n\n## printer.clear(instance)\nClear all current printed text.\n### PARAMETERS\n- `instance` printer instance, created by *printer.new*\n\n## printer.play_sound(name)\nThis function is called whenever a symbol is printed.\nTo play sound, you should override this function with your sound implementation.\n### PARAMETERS\n- `name` string, name of played sound --\u003e really just a container for whatever argument you might need here.\n*For a more complex implementation tied to the printer, create an external function and call it from here.*\n\n## printer.add_styles(styles)\nAdd custom styles to printer module\n### PARAMETERS\n- `styles` lua table with style parameters. Elements are: *{style_id: {params}}*\n\n## printer.add_source_style(source, style)\nAdd a source style to printer module.\n### PARAMETERS\n- `source` string, source id needed to index added style as source param in *printer.print* function\n- `style` string, style id\n\n## printer.add_word_style(word, style)\nAdd a word style to printer module.\n### PARAMETERS\n- `word` string, word to wrapped with specified style\n- `style` string, style id\n\n## printer.update(self, dt)\nUse in the gui `update()` function to update the printer instance.\n### PARAMETERS\n- `self` gui self context\n- `dt` dt parameter from update script\n\n## printer.final(self)\nUse in the gui `final()` function to correct final printer component.\n### PARAMETERS\n- `self` gui self context\n\n# Author\nInsality\n\n## 👏 Contributors\n\n\u003ca href=\"https://github.com/Insality/defold-printer/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contributors-img.web.app/image?repo=insality/defold-printer\"/\u003e\n\u003c/a\u003e\n\n\n## Changelog\n\n\u003cdetails\u003e\n\n### **1.1.0**\n- Improved functionality of creating new lines. Updated documentation, converted passive voice to active voice where possible. (@rocamocha)\n\n### **1.2.0**\n- Migrated to Defold 1.7.0\n\n### **1.2.1**\n- Fixed bug with node shaking (@farazk86)\n\n\u003c/details\u003e\n\n# License\nMy code is under MIT license\n\n[utf8 module](https://github.com/tst2005/lua-utf8string) MIT\n","funding_links":["https://github.com/sponsors/insality","https://ko-fi.com/insality","https://buymeacoffee.com/insality","https://www.buymeacoffee.com/insality"],"categories":["Libraries"],"sub_categories":["Programming Language"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FInsality%2Fdefold-printer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FInsality%2Fdefold-printer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FInsality%2Fdefold-printer/lists"}