Extension-Druid/README.md

Druid - powerful Defold component UI framework. Use huge list of embedeed Druid components or make your own game-specific components with ease to make stunning and customizable GUI in your games.

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 bindings. For custom input bindings see the Input Binding section in Advanced Setup.

Advanced Setup

In case you want to adjust Druid to your needs, you can use Advanced Setup section.

Usage

Basic usage

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

All Druid components take node name string as argument. In in some cases you don't have the node name you can pass the gui.get_node() instead.

All Druid and component methods are called with : like 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 a correct Druid workflow
function final(self)
    self.druid:final()
end

-- The update used in progress bar, scroll and timer basic components
function update(self, dt)
    self.druid:update(dt)
end

-- The on_message 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

-- The on_input used in almost all Druid components
function on_input(self, action_id, action)
    return self.druid:on_input(action_id, action)
end

For all Druid instance functions, see here.

API Documentation

Druid has a lot of components and functions. To make it easier to use, Druid has a full API documentation with examples and annotations.

Start read the API documentation here.

EmmyLua Annotations [optional]

EmmyLua - annotations for Lua. It's a great tool for Lua code autocompletion in editors like VSCode, IntelliJ IDEA.

Since the dependencies can't be processed by external editors, for use generated EmmyLua annotations you should copy the druid/annotations.lua to your project.

For EmmyLua it will be enough. Remember you can restart emmylua server for refresh the changes, if something goes wrong.

After the annotations is processed, you should point the type of Druid in requires:

---@type druid
local druid = require("druid.druid")

-- Now the autocomplete is working

Advanced Usage

If you looking for more advanced usage, see the Advanced Usage section.

Create custom components

If you want to create your own components, see the Create Custom Components section.

The custom components is the most powerful feature of Druid. You can create your own components with ease and use it in your game.

Druid Components

Here is full Druid components list.

Basic Components

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.	❌
Back Handler	Call callback on user "Back" action. It's a Android back button or keyboard backspace key	❌
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.	❌
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

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

Name	Description	Example	Preview
Checkbox	Switch node state on click event.	Checkbox Example
Checkbox group	Group of checkbox components.	Checkbox group Example
Radio group	Like checkbox group but with single choise only.	Radio Group Example
Dynamic Grid	Logic over GUI Node. Component to manage node positions with all different node sizes. Only one direction: horizontal or vertical.	Dynamic Grid 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	❌
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.	❌
Hotkey	Allow to set callbacks for keyboard hotkeys with key modificators.	Hotkey Example
Layout	Logic over GUI Node. Handle node size depends on layout mode and screen aspect ratio. Contains helpers to build more complex UI layout.	Layout Example

For a complete overview, see: components.md.

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 these events with the following API:

• event:subscribe(callback)

• event:unsubscribe(callback)

• event:clear()

You can subscribe several callbacks to a single event.

Details

• Druid input goes as stack. Last created button will be checked first. Create your input GUI component from back to front.
• Don't forget about return in on_input: return self.druid:on_input(). It is required if you have more than 1 acquire inputs (several Druid, other input system, etc)
• Druid automatically call acquire_input_focus if you have input components. So you don't required to call it manually.
• If you want to delete a Druid component node, don't forget to remove it via druid:remove(component)

See full FAQ here

Examples

HTML5 Live Examples

Try the HTML5 version of the Druid example app

Each example page has a link to the example code directly, so it will help you to faster understand how to use Druid

Code examples

See the example folder for examples of how to use Druid

Documentation

To better understand Druid, read the following documentation:

• Druid components
• Create custom components
• See FAQ article
• Druid styles

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!