Godot runtime
The Godot runtime is an addon written in GDScript, so there’s nothing to compile. The EnvyUI node reads a .envy.json document and builds real Control nodes from it: Panels, Containers, Labels and TextureRects. Focus, gamepad input and theming stay Godot’s own.
Requires Godot 4.3 or newer. Importing .envy.json as a resource, and live reload through it, needs Godot 4.6 or newer; on older versions point document_path at the file instead.
Install
- Copy
addons/envy_uiinto your project (it’s in every Godot package and AI handoff export) and enable Envy UI in Project Settings › Plugins. - Put your document in the project, for example
res://ui/my_ui.envy.json. In Godot 4.6+ it’s imported as an EnvyDocument resource. - Add an
EnvyUInode and set its document, or create it from code.
var ui := EnvyUI.new()
ui.document_path = "res://ui/my_ui.envy.json"
add_child(ui)
ui.ui_event.connect(_on_ui_event)
ui.set_data("player.hp", 40)
ui.goto("HUD")
ui.play("LevelUp")
ui.focus_first_button()Live reload
In Godot 4.6+, with the document imported as a resource and hot_reload on, saving the document reloads it in the running game. Link the document to the file in the editor and every Ctrl S shows up in Godot while you play.
Properties
| Property | Meaning |
|---|---|
document |
An EnvyDocument resource |
document_path |
Or a path to a .envy.json file |
start_screen |
Screen to show first (defaults to the first screen) |
scale_mode |
FIT scales the design resolution into the node and stretches to its aspect |
autoplay |
Play autoplay animations when a screen shows |
use_sample_data |
Start with the document’s sample data |
hot_reload |
Reload when the document changes on disk |
locale |
Locale for translated text |
fonts |
Family name → Font, for fonts the document doesn’t embed |
cancel_closes_overlay |
ui_cancel closes the top overlay |
Methods
| Method | Does |
|---|---|
goto(screen, transition = {}) |
Shows a screen by name or id |
push(screen, transition = {}), pop() |
Opens an overlay, closes the top one |
get_stack(), get_screen_names() |
The open screens, every screen |
set_data(path, value), merge_data(patch), get_data(path) |
Data |
play(anim), stop(anim), is_playing(anim) |
Animations |
set_locale(locale), get_locales() |
Language |
get_control(name_or_id) |
The Control built for a layer |
focus_first_button() |
Starts keyboard and gamepad navigation |
load_document(path), load_resource(res) |
Loads another document |
Signals
| Signal | When |
|---|---|
ui_event(event, payload) |
A button emitted an event |
screen_changed(screen_name) |
goto, push or pop ran |
data_changed(data) |
A button set or toggled data |
document_reloaded |
The document changed on disk and was reloaded |
Tests
The addon has a headless test suite: godot --headless --path runtimes/godot -s res://tests/run_tests.gd. See known differences for where Godot and the web draw slightly differently.