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.
Check the HTML5 version of the Druid example app.
In 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.
To integrate the Druid extension into your own project, add this project as a dependency in your Defold game. Open your game.project file and add the following line to the dependencies field under the project section:
Druid v1.0
Here is a list of all releases.
Note: The library size is calculated based on the build report per platform. The extended components are exlcuded, which are including only on demand.
| Platform | Library Size |
|---|---|
| HTML5 | 38.00 KB |
| Desktop / Mobile | 65.74 KB |
Druid utilizes the /builtins/input/all.input_binding input bindings. Either use this file for your project by setting the Runtime -> Input -> 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.
To 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.
When 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.
All Druid and component methods are invoked using the : operator, such as self.druid:new_button().
local druid = require("druid.druid")
-- All component callbacks pass "self" as first argument
-- This "self" is a context data passed in `druid.new(context)`
local function on_button_callback(self)
print("The button clicked!")
end
function init(self)
self.druid = druid.new(self)
self.button = self.druid:new_button("button_node_name", on_button_callback)
end
-- "final" is a required function for the correct Druid workflow
function final(self)
self.druid:final()
end
-- "update" is used in progress bar, scroll, and timer basic components
function update(self, dt)
self.druid:update(dt)
end
-- "on_message" is used for specific Druid events, like language change or layout change
function on_message(self, message_id, message, sender)
self.druid:on_message(message_id, message, sender)
end
-- "on_input" is used in almost all Druid components
-- The return value from `druid:on_input` is required!
function on_input(self, action_id, action)
return self.druid:on_input(action_id, action)
end
For all Druid instance functions, see here.
Druid offers a wide range of components and functions. To facilitate usage, Druid provides comprehensive API documentation with examples and annotations.
Start reading the API documentation here.
Druid provide the EmmyLua annotations to add autocomplete inside your IDE. Check EmmyLua Setup here.
If you want to create your own components, refer to the Create Custom Components section in the documentation.
Custom 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.
Here is full Druid components list.
Basic components always included in the build and available for use.
| Name | Description | Example | Preview |
|---|---|---|---|
| Button | Logic over GUI Node. Handle the user click interactions: click, long click, double click, etc. | Button Example |  |
| Text | Logic over GUI Text. By default Text component fit the text inside text node size area with different adjust modes. | Text Example |  |
| Scroll | Logic over two GUI Nodes: input and content. Provides basic behaviour for scrollable content. | Scroll Example |  |
| Blocker | Logic over GUI Node. Don't pass any user input below node area size. | Blocker Example |  |
| Back Handler | Call callback on user "Back" action. It's a Android back button or keyboard backspace key | Back Handler Example |  |
| Static Grid | Logic over GUI Node. Component to manage node positions with all equal node sizes. | Static Gid Example |  |
| Hover | Logic over GUI Node. Handle hover action over node. For both: mobile touch and mouse cursor. | Hover Example |  |
| Swipe | Logic over GUI Node. Handle swipe gestures over node. | Swipe Example |  |
| Drag | Logic over GUI Node. Handle drag input actions. Can be useful to make on screen controlls. | Drag Example |  |
Extended components before usage should be registered in Druid with
druid.register()function. On usage of unregistered Druid component the next log will be shown in the console.
local data_list = require("druid.extended.data_list")
druid.register("data_list", data_list)
| Name | Description | Example | Preview |
|---|---|---|---|
| Data List | Logic over Scroll and Grid components. Create only visible GUI nodes or components to make "infinity" scroll befaviour | Data List Example |  |
| Input | Logic over GUI Node and GUI Text (or Text component). Provides basic user text input. | Input Example |  |
| Lang text | Logic over Text component to handle localization. Can be translated in real-time with druid.on_language_change |
Lang Text Example |  |
| Progress | Logic over GUI Node. Handle node size and scale to handle progress node size. | Progress Example |  |
| Slider | Logic over GUI Node. Handle draggable node with position restrictions. | Slider Example |  |
| Timer | Logic over GUI Text. Handle basic timer functions. | Timer Example |  |
| Hotkey | Allow to set callbacks for keyboard hotkeys with key modificators. | Hotkey Example |  |
| Layout | Logic over GUI Node. Arrange nodes inside layout node with margin/paddings settings. | Layout Example |  |
| Rich Input | Logic over GUI Node and GUI Text (or Text component). Provides rich text input with different styles and text formatting. | Rich Input Example |  |
| Rich Text | Logic over GUI Text. Provides rich text formatting with different styles and text formatting. | Rich Text Example |  |
For a complete overview, see: components.md.
Any Druid components as callbacks use Druid Events. In component API (button example) pointed list of component events. You can manually subscribe to these events with the following API:
-
event:subscribe(callback)
-
event:unsubscribe(callback)
-
event:clear()
You can subscribe several callbacks to a single event.
- 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.
- Remember to include
returnin theon_inputfunction:return self.druid:on_input(). This is necessary if you have multiple input sources (multiple Druid instances, other input systems, etc.). - Druid automatically calls
acquire_input_focusif you have input components. Therefore, manual calling ofacquire_input_focusis not required. - When deleting a Druid component node, make sure to remove it using
druid:remove(component).
Try the HTML5 version of the Druid example app.
Each example page provides a direct link to the corresponding example code, making it easier for you to understand how to use Druid.
Or refer directly to the example folder for code examples demonstrating how to use Druid.
To better understand Druid, read the following documentation:
You can find the full Druid documentation here.
If you have any issues, questions or suggestions please create an issue or contact me: [email protected]
For a complete history of the development of Druid, please check the changelog.
Your donation helps me stay engaged in creating valuable projects for Defold. If you appreciate what I'm doing, please consider supporting me!