Druid - a powerful, flexible and easy to use Defold component UI framework. Contains a wide range of components and features to create stunning and customizable GUIs. Provides a powerful way to create, compose and manage your custom components and scenes.

Druid Example

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.

Setup

Dependency

Open your game.project file and add the following lines to the dependencies field under the project section:

Druid

https://github.com/Insality/druid/archive/refs/tags/1.0.zip

Defold Event

https://github.com/Insality/defold-event/archive/refs/tags/10.zip

After that, select Project ▸ Fetch Libraries to update library dependencies. This happens automatically whenever you open a project so you will only need to do this if the dependencies change without re-opening the project.

Here is a list of all releases.

Library Size

Note: The library size is calculated based on the build report per platform.

Platform	Full Size
HTML5	84.52 KB
Desktop / Mobile	141.03 KB

Input Bindings

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.

Usage

Basic usage

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 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.

Default GUI Script

Put the following code in your GUI script to start using Druid.

local druid = require("druid.druid")

function init(self)
	self.druid = druid.new(self)
end

function final(self)
	self.druid:final()
end

function update(self, dt)
	self.druid:update(dt)
end

function on_message(self, message_id, message, sender)
	self.druid:on_message(message_id, message, sender)
end

function on_input(self, action_id, action)
	return self.druid:on_input(action_id, action)
end

Default Widget Template

Create a new lua file to create a new widget class. This widget can be created with self.druid:new_widget(widget_class, [template], [nodes])

Usually this widget lua file is placed nearby with the GUI file it belong to and have the same name.

---@class your_widget_class: druid.widget
local M = {}

function M:init()
	self.root = self:get_node("root")
	self.button = self.druid:new_button("button", self.on_click)
end

function M:on_click()
	print("Button clicked!")
end

return M

API Documentation

Best start is from the Quick API Reference

With next quick links:

• Druid Instance - Druid instance returned from druid.new(self)
• Helper - A lot of useful functions
• Widgets - About widgets and how to use them

Druid Components

Here is full Druid components list.

Components

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
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.

Druid Events

All Druid components using Defold Event for components callbacks. 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)

You can subscribe several callbacks to a single event.

Examples:

button.on_click_event:subscribe(function(self, args)
	print("Button clicked!")
end)

scroll.on_scroll:subscribe(function(self, position)
	print("Scroll scrolled!")
end)

input.on_input_unselect:subscribe(function(self, text)
	print("User enter input:", text)
end)

Details

• 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 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.).
• Druid automatically calls acquire_input_focus if you have input components. Therefore, manual calling of acquire_input_focus is not required.
• When deleting a Druid component node, make sure to remove it using druid:remove(component).

Examples

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.

Documentation

You can find the full Druid functions at Quick API Reference

To better understand Druid, read the following documentation:

• How To GUI in Defold
• Widgets
• Create custom components
• Druid styles

Licenses

This project is licensed under the MIT License - see the LICENSE file for details.

Issues and suggestions

If you have any issues, questions or suggestions please create an issue or contact me: insality@gmail.com

History

For a complete history of the development of Druid, please check the changelog.

👏 Contributors

❤️ Support project ❤️

Your donation helps me stay engaged in creating valuable projects for Defold. If you appreciate what I'm doing, please consider supporting me!