Druid-Extension

Druid - powerful Defold component UI library. Use basic and extended Druid components or make your own game-specific components to make amazing GUI in your games.

Overview

Setup

Dependency

You can use the Druid extension in your own project by adding this project as a Defold library dependency. Open your game.project file and in the dependencies field under project add:

Druid v0.10.3

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

Here is a list of all releases.

Input Bindings

Druid uses /builtins/input/all.input_binding input bindins. For advanced setup see the Input Binding section in Advanced Setup.

Usage

Here only basic usage. How to read this doc. Annotations. Example of advanced usage - different doc. Example of custom components - different doc.

Components

Here is full Druid components list:

Basic Components

Name	Description	Example
Button	Basic input component. Handles all types of interactions: click, long click, hold click, double click, etc	Button Example
Text	Wrap on GUI text node, handle different text size adjusting, providing additional text API	Text Example
Scroll	Scroll component	Scroll Example
Blocker	Block user input in node zone area	❌
Back Handler	Handle back button (Android back button, backspace key)	❌
Static Grid	Component to manage node positions with equal sizes	Static Gid Example
Hover	Handle hover node state on node	❌
Swipe	Handle swipe gestures on node	Swipe Example
Drag	Handle drag input on node	Drag Example

Extended components

Extended components before usage should be registered in Druid with druid.register() function.

Name	Description	Example
Checkbox	Checkbox component	Checkbox Example
Checkbox group	Several checkboxes in one group	Checkbox group Example
Radio group	Several checkboxes in one group with a single choice	Radio Group Example
Dynamic Grid	Component to manage node positions with different sizes. Only in one row or column	Dynamic Grid Example
Data List	Component to manage data for huge datasets in scroll	Data List Example
Input	User text input component	Input Example
Lang text	Wrap on Text component to handle localization	❌
Progress	Progress bar component	Progress Example
Slider	Slider component	Slider Example
Timer	Handle timers on GUI text node	❌
Hotkey	Handle keyboard hotkeys with key modificators	Hotkey Example
Layout	Handle node size depends on layout mode and screen aspect ratio	Layout Example

For a complete overview, see: components.md.

Basic usage

To use Druid, first you should create a Druid instance to spawn components and add Druids main engine functions: update, final, on_message and on_input.

All Druid components take node name string as arguments, don't do gui.get_node() before.

All Druid and component methods are called with : like self.druid:new_button().

local druid = require("druid.druid")

local function button_callback(self)
    print("Button was clicked!")
end

function init(self)
    self.druid = druid.new(self)
    self.druid:new_button("button_node_name", button_callback)
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

For all Druid instance functions, see here.

Druid Events

Any Druid components as callbacks use Druid Events. In component API (button example) pointed list of component events. You can manually subscribe to those events with the following API:

event:subscribe(callback)
event:unsubscribe(callback)
event:clear()

You can subscribe several callbacks to a single event.

Druid Lifecycle

Here is full Druid lifecycle setup for your *.gui_script file:

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_input(self, action_id, action)
    return self.druid:on_input(action_id, action)
end

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

final is a required function for a correct Druid lifecycle
on_input is used in almost all Druid components
update in used in progress bar, scroll and timer base components
on_message is used for specific Druid events, like language change or layout change

It is recommended to fully integrate all Druid lifecycles functions.

Details

Druid input goes as stack. Last created button will checked first. So create your GUI from back
Don't forget about return in on_input: return self.druid:on_input(). It is needed if you have more than 1 acquire inputs (several Druid, other input system, etc)
By default, Druid will automatically acquire_input_focus. So you don't need do it manually. But only if you have components which require on_input
If you want to delete a node which has a Druid component, don't forget to remove it via druid:remove(component)

See full FAQ here

Examples

See the example folder for examples of how to use Druid

Try the HTML5 version of the Druid example app

Documentation

To better understand Druid, read the following documentation:

You can fund the full Druid documentation here: https://insality.github.io/druid/

License

Developed and supported by Insality
Original idea by AGulev
Assets from Kenney

Issues and suggestions

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

❤️ 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!