{"id":15722616,"url":"https://github.com/insality/druid","last_synced_at":"2025-05-15T20:05:46.561Z","repository":{"id":43222399,"uuid":"177656617","full_name":"Insality/druid","owner":"Insality","description":"Powerful Defold UI component framework","archived":false,"fork":false,"pushed_at":"2025-05-13T18:43:17.000Z","size":54788,"stargazers_count":451,"open_issues_count":12,"forks_count":46,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-15T20:05:31.821Z","etag":null,"topics":["defold","defold-game-engine","defold-library","defold-module","ui"],"latest_commit_sha":null,"homepage":"https://insality.github.io/druid/","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":"CONTRIBUTING.md","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,"zenodo":null},"funding":{"github":"insality","ko_fi":"insality","buy_me_a_coffee":"insality"}},"created_at":"2019-03-25T20:08:36.000Z","updated_at":"2025-05-15T10:34:32.000Z","dependencies_parsed_at":"2024-03-21T17:28:39.479Z","dependency_job_id":"182a4b52-e966-425b-9b1d-6748accb052e","html_url":"https://github.com/Insality/druid","commit_stats":{"total_commits":697,"total_committers":13,"mean_commits":53.61538461538461,"dds":"0.045911047345767564","last_synced_commit":"d2b617a14f3dbf97c050607e5dc8506ffb935f35"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdruid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdruid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdruid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdruid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Insality","download_url":"https://codeload.github.com/Insality/druid/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414499,"owners_count":22067272,"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-game-engine","defold-library","defold-module","ui"],"created_at":"2024-10-03T22:08:39.128Z","updated_at":"2025-05-15T20:05:41.487Z","avatar_url":"https://github.com/Insality.png","language":"Lua","funding_links":["https://github.com/sponsors/insality","https://ko-fi.com/insality","https://buymeacoffee.com/insality","https://www.buymeacoffee.com/insality"],"categories":[],"sub_categories":[],"readme":"\n[![](media/druid_logo.png)](https://insality.github.io/druid/)\n\n[![GitHub release (latest by date)](https://img.shields.io/github/v/tag/insality/druid?style=for-the-badge\u0026label=Release)](https://github.com/Insality/druid/tags)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/insality/druid/ci-workflow.yml?branch=master\u0026style=for-the-badge)](https://github.com/Insality/druid/actions)\n[![codecov](https://img.shields.io/codecov/c/github/Insality/druid?style=for-the-badge)](https://codecov.io/gh/Insality/druid)\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**Druid** - powerful **Defold** component UI framework that empowers developers to create stunning and customizable GUIs by leveraging a wide range of embedded components or effortlessly designing their own game-specific components.\n\n## Druid Example\n\nCheck the [**HTML5 version**](https://insality.github.io/druid/druid/) of the **Druid** example app.\n\nIn this example you can inspect a variety of **Druid** components and see how they work. Each example page provides a direct link to the corresponding example code, making it easier for you to understand how to use **Druid**.\n\n## Setup\n\n### Dependency\n\nTo integrate the **Druid** extension into your own project, add this project as a [dependency](https://www.defold.com/manuals/libraries/) in your **Defold** game. Open your `game.project` file and add the following line to the dependencies field under the project section:\n\n**Druid v1.0.1**\n\n\u003e [https://github.com/Insality/druid/archive/refs/tags/1.0.1.zip](https://github.com/Insality/druid/archive/refs/tags/1.0.1.zip)\n\nHere is a list of [all releases](https://github.com/Insality/druid/releases).\n\n\n### Library Size\n\n\u003e **Note:** The library size is calculated based on the build report per platform. The extended components are exlcuded, which are including only on demand.\n\n| Platform         | Library Size  |\n| ---------------- | ------------- |\n| HTML5            | **38.00 KB**  |\n| Desktop / Mobile | **65.74 KB**  |\n\n\n### Input Bindings\n\n**Druid** utilizes the `/builtins/input/all.input_binding` input bindings. Either use this file for your project by setting the `Runtime -\u003e Input -\u003e Game Binding` field in the `game.project` input section to `/builtins/input/all.input_binding`, or add the specific bindings you need to your game's input binding file. For custom input bindings, refer to the Input Binding section in the [Advanced Setup](https://github.com/Insality/druid/blob/master/docs_md/advanced-setup.md#input-bindings).\n\n\n## Usage\n\n### Basic usage\n\nTo utilize **Druid**, begin by creating a **Druid** instance to instantiate components and include the main functions of **Druid**: *update*, *final*, *on_message*, and *on_input*.\n\nWhen using **Druid** components, provide a node name string as an argument. If you don't have the node name available in some cases, you can pass `gui.get_node()` instead.\n\nAll **Druid** and component methods are invoked using the `:` operator, such as `self.druid:new_button()`.\n\n```lua\nlocal druid = require(\"druid.druid\")\n\n-- All component callbacks pass \"self\" as first argument\n-- This \"self\" is a context data passed in `druid.new(context)`\nlocal function on_button_callback(self)\n    print(\"The button clicked!\")\nend\n\nfunction init(self)\n    self.druid = druid.new(self)\n    self.button = self.druid:new_button(\"button_node_name\", on_button_callback)\nend\n\n-- \"final\" is a required function for the correct Druid workflow\nfunction final(self)\n    self.druid:final()\nend\n\n-- \"update\" is used in progress bar, scroll, and timer basic components\nfunction update(self, dt)\n    self.druid:update(dt)\nend\n\n-- \"on_message\" is used for specific Druid events, like language change or layout change\nfunction on_message(self, message_id, message, sender)\n    self.druid:on_message(message_id, message, sender)\nend\n\n-- \"on_input\" is used in almost all Druid components\n-- The return value from `druid:on_input` is required!\nfunction on_input(self, action_id, action)\n    return self.druid:on_input(action_id, action)\nend\n\n```\n\nFor all **Druid** instance functions, [see here](https://insality.github.io/druid/modules/DruidInstance.html).\n\n\n### API Documentation\n\n**Druid** offers a wide range of components and functions. To facilitate usage, **Druid** provides comprehensive API documentation with examples and annotations.\n\nStart reading the API documentation [here](https://insality.github.io/druid/modules/Druid.html).\n\n**Druid** provide the *EmmyLua* annotations to add autocomplete inside your IDE. Check [EmmyLua Setup here](docs_md/advanced-setup.md#emmylua-annotations).\n\n\n### Create custom components\n\nIf you want to create your own components, refer to the [Create Custom Components](docs_md/02-creating_custom_components.md) section in the documentation.\n\nCustom components are one of the most powerful features of **Druid**. They allow you to create your own components effortlessly and utilize them in your game.\n\n\n## Druid Components\n\nHere is full **Druid** components list.\n\n### Basic Components\n\n\u003e Basic components always included in the build and available for use.\n\n| Name | Description | Example | \u003cdiv style=\"width:200px\"\u003ePreview\u003c/div\u003e |\n|------|-------------|---------|---------|\n| **[Button](https://insality.github.io/druid/modules/Button.html)** | Logic over GUI Node. Handle the user click interactions: click, long click, double click, etc. | [Button Example](https://insality.github.io/druid/druid/?example=general_buttons) | \u003cimg src=\"media/preview/button.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Text](https://insality.github.io/druid/modules/Text.html)** | Logic over GUI Text. By default Text component fit the text inside text node size area with different adjust modes. | [Text Example](https://insality.github.io/druid/druid/?example=texts_general) | \u003cimg src=\"media/preview/text.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Scroll](https://insality.github.io/druid/modules/Scroll.html)** | Logic over two GUI Nodes: input and content. Provides basic behaviour for scrollable content. | [Scroll Example](https://insality.github.io/druid/druid/?example=general_scroll) | \u003cimg src=\"media/preview/scroll.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Blocker](https://insality.github.io/druid/modules/Blocker.html)** | Logic over GUI Node. Don't pass any user input below node area size. | [Blocker Example](https://insality.github.io/druid/druid/?example=timer) | \u003cimg src=\"media/preview/blocker.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Back Handler](https://insality.github.io/druid/modules/BackHandler.html)** | Call callback on user \"Back\" action. It's a Android back button or keyboard backspace key | [Back Handler Example](https://insality.github.io/druid/druid/?example=timer) | \u003cimg src=\"media/preview/back_handler.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Static Grid](https://insality.github.io/druid/modules/StaticGrid.html)** | Logic over GUI Node. Component to manage node positions with all equal node sizes. | [Static Gid Example](https://insality.github.io/druid/druid/?example=general_grid) | \u003cimg src=\"media/preview/static_grid.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Hover](https://insality.github.io/druid/modules/Hover.html)** | Logic over GUI Node. Handle hover action over node. For both: mobile touch and mouse cursor. | [Hover Example](https://insality.github.io/druid/druid/?example=timer) | \u003cimg src=\"media/preview/hover.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Swipe](https://insality.github.io/druid/modules/Swipe.html)** | Logic over GUI Node. Handle swipe gestures over node. | [Swipe Example](https://insality.github.io/druid/druid/?example=general_swipe) | \u003cimg src=\"media/preview/swipe.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Drag](https://insality.github.io/druid/modules/Drag.html)** | Logic over GUI Node. Handle drag input actions. Can be useful to make on screen controlls. | [Drag Example](https://insality.github.io/druid/druid/?example=general_drag) | \u003cimg src=\"media/preview/drag.gif\" width=\"200\" height=\"100\"\u003e |\n\n\n### Extended components\n\n\u003e Extended components before usage should be registered in **Druid** with [`druid.register()`](https://insality.github.io/druid/modules/Druid.html#druid.register) function.\n\u003e On usage of unregistered **Druid** component the next log will be shown in the console.\n```\nlocal data_list = require(\"druid.extended.data_list\")\ndruid.register(\"data_list\", data_list)\n```\n\n| Name | Description | Example | \u003cdiv style=\"width:200px\"\u003ePreview\u003c/div\u003e |\n|------|-------------|---------|---------|\n| **[Data List](https://insality.github.io/druid/modules/DataList.html)** | Logic over Scroll and Grid components. Create only visible GUI nodes or components to make \"infinity\" scroll befaviour | [Data List Example](https://insality.github.io/druid/druid/?example=general_data_list) | \u003cimg src=\"media/preview/data_list.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Input](https://insality.github.io/druid/modules/Input.html)** | Logic over GUI Node and GUI Text (or Text component). Provides basic user text input. | [Input Example](https://insality.github.io/druid/druid/?example=general_input) | \u003cimg src=\"media/preview/input.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Lang text](https://insality.github.io/druid/modules/LangText.html)** | Logic over Text component to handle localization. Can be translated in real-time with `druid.on_language_change` | [Lang Text Example](https://insality.github.io/druid/druid/?example=timer) | \u003cimg src=\"media/preview/lang_text.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Progress](https://insality.github.io/druid/modules/Progress.html)** | Logic over GUI Node. Handle node size and scale to handle progress node size. | [Progress Example](https://insality.github.io/druid/druid/?example=general_progress_bar) | \u003cimg src=\"media/preview/progress.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Slider](https://insality.github.io/druid/modules/Slider.html)** | Logic over GUI Node. Handle draggable node with position restrictions. | [Slider Example](https://insality.github.io/druid/druid/?example=general_sliders) | \u003cimg src=\"media/preview/slider.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Timer](https://insality.github.io/druid/modules/Timer.html)** | Logic over GUI Text. Handle basic timer functions. | [Timer Example](https://insality.github.io/druid/druid/?example=timer) | \u003cimg src=\"media/preview/timer.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Hotkey](https://insality.github.io/druid/modules/Hotkey.html)** | Allow to set callbacks for keyboard hotkeys with key modificators. | [Hotkey Example](https://insality.github.io/druid/druid/?example=general_hotkey) | \u003cimg src=\"media/preview/hotkey.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Layout](https://insality.github.io/druid/modules/Layout.html)** | Logic over GUI Node. Arrange nodes inside layout node with margin/paddings settings. | [Layout Example](https://insality.github.io/druid/druid/?example=general_layout) | \u003cimg src=\"media/preview/layout.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Rich Input](https://insality.github.io/druid/modules/RichInput.html)** | Logic over GUI Node and GUI Text (or Text component). Provides rich text input with different styles and text formatting. | [Rich Input Example](https://insality.github.io/druid/druid/?example=general_rich_input) | \u003cimg src=\"media/preview/rich_input.gif\" width=\"200\" height=\"100\"\u003e |\n| **[Rich Text](https://insality.github.io/druid/modules/RichText.html)** | Logic over GUI Text. Provides rich text formatting with different styles and text formatting. | [Rich Text Example](https://insality.github.io/druid/druid/?example=general_rich_text) | \u003cimg src=\"media/preview/rich_text.gif\" width=\"200\" height=\"100\"\u003e |\n\nFor a complete overview, see: **_[components.md](docs_md/01-components.md)_**.\n\n\n## Druid Events\n\nAny **Druid** components as callbacks use [Druid Events](https://insality.github.io/druid/modules/DruidEvent.html). In component API ([button example](https://insality.github.io/druid/modules/Button.html#on_click)) pointed list of component events. You can manually subscribe to these events with the following API:\n\n- **event:subscribe**(callback)\n\n- **event:unsubscribe**(callback)\n\n- **event:clear**()\n\nYou can subscribe several callbacks to a single event.\n\n## Details\n\n- **Druid** processes input in a stack-based manner. The most recently created button will be checked first. Create your input GUI components from back to front.\n- Remember to include `return` in the `on_input` function: `return self.druid:on_input()`. This is necessary if you have multiple input sources (multiple Druid instances, other input systems, etc.).\n- Druid automatically calls `acquire_input_focus` if you have input components. Therefore, manual calling of `acquire_input_focus` is not required.\n- When deleting a **Druid** component node, make sure to remove it using `druid:remove(component)`.\n\n\n## Examples\n\nTry the [**HTML5 version**](https://insality.github.io/druid/druid/) of the **Druid** example app.\n\nEach example page provides a direct link to the corresponding example code, making it easier for you to understand how to use **Druid**.\n\nOr refer directly to the [**example folder**](https://github.com/Insality/druid/tree/develop/example) for code examples demonstrating how to use **Druid**.\n\n## Documentation\n\nTo better understand **Druid**, read the following documentation:\n- [How To GUI in Defold](https://forum.defold.com/t/how-to-gui-in-defold/73256)\n- [Druid components](docs_md/01-components.md)\n- [Create custom components](docs_md/02-creating_custom_components.md)\n- [See FAQ article](docs_md/FAQ.md)\n- [Druid styles](docs_md/03-styles.md)\n\nYou can find the full **Druid** [documentation here](https://insality.github.io/druid/modules/Druid.html).\n\n\n## Licenses\n\n- Developed and supported by [Insality](https://github.com/Insality)\n- Original idea by [AGulev](https://github.com/AGulev)\n- Assets from [Kenney](http://www.kenney.nl/)\n\n\n## Issues and suggestions\n\nIf you have any issues, questions or suggestions please [create an issue](https://github.com/Insality/druid/issues) or contact me: [insality@gmail.com](mailto:insality@gmail.com)\n\n\n## History\nFor a complete history of the development of **Druid**, please check the [changelog](docs_md/changelog.md).\n\n\n## 👏 Contributors\n\n\u003ca href=\"https://github.com/Insality/druid/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contributors-img.web.app/image?repo=insality/druid\"/\u003e\n\u003c/a\u003e\n\n\n## ❤️ Support project ❤️\n\nYour donation helps me stay engaged in creating valuable projects for **Defold**. If you appreciate what I'm doing, please consider supporting me!\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsality%2Fdruid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finsality%2Fdruid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsality%2Fdruid/lists"}