# Envy documentation

---



---

> Envy is a game UI editor. Design menus, HUDs and inventories on one canvas, then run the same file natively in Godot 4 and in the browser, with a contract your programmers or coding agents can wire up.

---



---

# Quick start

> Make your first game UI screen in Envy (alpha), preview it, and run it in Godot 4 or a web page. Takes about ten minutes.

Source: https://envyui.com/docs/quick-start

Envy is a game UI editor. You draw screens on a canvas, and the same file runs natively in Godot 4 and in the browser. This page takes you from an empty project to a menu running in your game.

## 1. Open the editor

Envy is in alpha: [join the waitlist](/waitlist) for access. The editor runs in a desktop browser with no install. Your work is saved in the browser as you go, and **Ctrl S** saves it to a `.envy.json` file on disk.

Choose **New project**. You can start blank, from the [starter kit](/kit) (15 screens on one token set), or from a showcase project like [The Last Hunt](/showcase).

## 2. Draw a screen

- Press **F** for a frame, **T** for text, **B** for a button. **V** goes back to select.
- Select a few layers and press **Shift A** to put them in an auto-layout row or column. In Godot they become box containers.
- Pin layers to edges with the anchor widget in the inspector, so the screen holds at other aspect ratios. See [Layout](/docs/layout).
- Select a layer and press **Ctrl Alt K** to turn it into a component. Copies stay in step with it. See [Components](/docs/components).

## 3. Make it do something

- On a button, add a click action: **Emit event** `start_game`, **Go to screen**, **Push** an overlay, **Set** or **Toggle** data, or **Play** an animation.
- Bind a text or progress layer to a data path like `player.hp`, or write `HP {player.hp}` in a text layer.
- Give the document sample data so the canvas looks alive. See [Data and events](/docs/data).

Press **Ctrl Enter** to preview. Buttons, transitions and animations run for real.

## 4. Run it in your game

Press **Ctrl E** to export.

**Godot 4.3+**: export the **Godot package**, copy `addons/envy_ui` into your project, enable the plugin and add an `EnvyUI` node:

```gdscript
var ui := EnvyUI.new()
ui.document_path = "res://ui/my_ui.envy.json"
add_child(ui)
ui.ui_event.connect(func(event, payload):
	if event == "start_game": start_game())
ui.set_data("player.hp", 72)
```

**Web**: load the runtime and mount the document into any element:

```html
<div id="ui" style="width: 100vw; height: 100vh"></div>
<script src="envy-runtime.js"></script>
<script type="module">
  const doc = await fetch("ui/my_ui.envy.json").then((r) => r.json());
  const ui = Envy.mount(document.getElementById("ui"), doc);
  ui.on("start_game", () => game.start());
  ui.setData("player.hp", 72);
</script>
```

## 5. Hand it off

Export **AI handoff** to get a zip a programmer or a coding agent can work from: AGENTS.md, the event and data contract, screenshots and typed code for Godot and TypeScript. See [Handoff](/docs/handoff).

## Next

- [The editor](/docs/editor): canvas, panels and shortcuts.
- [Godot runtime](/docs/godot) and [web runtime](/docs/web).
- [The document format](/docs/format), if you want to read or write `.envy.json` by hand.


---

# The editor

> How Envy's game UI editor is laid out, the tools on the canvas, previewing, saving and the keyboard shortcuts you'll use every day.

Source: https://envyui.com/docs/editor

The editor is a web app. The canvas in the middle is the web runtime in design mode, so what you see while you edit is what ships.

## Layout

- **Layers** on the left: every screen and component board, and the layer tree of the one you're in, with a search box.
- **Canvas** in the middle: screens and component boards side by side. Pan with Space or the hand tool, zoom with Ctrl + scroll.
- **Inspector** on the right: layout, style, text, interaction, bindings, focus and notes for the selection.
- **Timeline** at the bottom (**Alt T**): keyframe animation for the current screen.

Hide panels to get room: **Ctrl \\** hides both, **Ctrl Alt \\** the left one, **Ctrl Shift \\** the right one. Drag a panel's edge to resize it.

## Selecting

Click selects the top-level layer under the pointer, double-click goes one level deeper, and Ctrl-click picks the deepest layer. Drag on empty canvas to marquee-select. Arrow keys nudge by 1 px, Shift with an arrow by 10.

## Tools

| Key | Tool |
|---|---|
| V | Select |
| H | Hand (pan) |
| F | Frame |
| R | Rectangle |
| O | Ellipse |
| L | Line |
| N | Pen (vector paths) |
| T | Text |
| B | Button |
| I | Image |
| P | Progress bar |

## Everyday shortcuts

| Keys | Action |
|---|---|
| Ctrl S / Ctrl O | Save to file / open a file |
| Ctrl E | Export |
| Ctrl Enter | Preview |
| Ctrl Z / Ctrl Shift Z | Undo / redo |
| Ctrl D | Duplicate |
| Ctrl G / Ctrl Shift G | Wrap in a frame / unwrap |
| Shift A | Auto layout on or off (wraps a multi-selection in a row) |
| Ctrl Alt K | Create a component from the selection |
| Ctrl Alt B | Detach an instance |
| Ctrl Alt C / Ctrl Alt V | Copy / paste properties |
| Ctrl ] / Ctrl [ | Bring forward / send backward (Shift for front and back) |
| Ctrl Shift H / Ctrl Shift L | Hide / lock |
| Ctrl A | Select all layers next to the selection |
| Shift R | Rulers |
| Ctrl ; / Ctrl ' | Guides / layout grids |
| Shift 1 / Shift 2 | Zoom to fit / zoom to selection |
| Ctrl 0 | Zoom to 100% |
| Alt T | Timeline |
| ? | All shortcuts |

Hold **Alt** over a layer to measure the distance to the selection.

## Saving

The editor autosaves every document in your browser and shows whether the last save worked. To keep a file in your game's repository, link the document to a `.envy.json` file: after that, **Ctrl S** writes straight to it, and Godot picks up the change while the game runs (see [Godot runtime](/docs/godot)).

## Checks

**Document checks** list problems before you export: missing tokens, screens, assets or focus targets, data paths without a sample value, untranslated keys and more. The same checks run in the CLI as `envy validate`.

> The site shows the editor's next design (v2), which is in development. Today's editor has the same canvas, runtime and features in a simpler layout.


---

# Layout

> Anchors, offsets and auto layout in Envy work like Godot's Control anchors and box containers, so one layout holds at 16:9, 21:9, 16:10 and 4:3.

Source: https://envyui.com/docs/layout

Envy's layout model is Godot's. Every layer has **anchors** and **offsets** like a Godot `Control`, and frames can lay out their children automatically like `HBoxContainer` and `VBoxContainer`. Nothing is translated on export: the Godot runtime copies the numbers 1:1.

## Anchors and offsets

Anchors are fractions of the parent rectangle, from 0 to 1, for the left, top, right and bottom edges. Offsets are pixels added to the anchored edges.

| Anchors (l, t, r, b) | Behaves like |
|---|---|
| 0, 0, 0, 0 | Pinned to the top-left corner (the default) |
| 1, 0.5, 1, 0.5 | Pinned to the right edge, centered vertically |
| 0, 1, 1, 1 | Stretches along the bottom edge |
| 0, 0, 1, 1 | Fills the parent |

In The Last Hunt's main menu, the menu is anchored right and middle, the last-save card to the bottom right, and the header stretches across the top. Change the screen to 21:9 or 4:3 and each group stays where it belongs, with no second layout. You can see it on the [home page](/#design).

In the inspector, the anchor widget sets common presets in one click, and the raw numbers are there when you need them.

## Auto layout

A frame or button can arrange its children in a **row** or a **column** (Shift A toggles it):

- `gap` between children, `padding` inside the frame.
- `align` on the cross axis (start, center, end) and `justify` on the main axis (start, center, end, space-between).
- `wrap` moves children onto new lines, with `lineGap` between lines.

Children inside auto layout size themselves with **fixed**, **fill** or **hug** on each axis.

| Envy | Godot | Web |
|---|---|---|
| Row / column | `PanelContainer` › `HBoxContainer` / `VBoxContainer` | Flexbox |
| Wrap | `HFlowContainer` / `VFlowContainer` | `flex-wrap` |
| Padding | Content margins | Padding |
| Fill | `SIZE_EXPAND_FILL` | `flex: 1` |
| Space-between | Expanding spacers | `justify-content: space-between` |

## Scaling

Both runtimes scale the screen's design resolution to fit the window and stretch the root to the window's aspect ratio, like Godot's `canvas_items` stretch mode with `expand`. Anchors decide how each layer follows.

## Rotation

`rotation` turns a layer around its center in degrees. It doesn't affect layout.

## Design aids

Rulers (Shift R), guides dragged off the rulers, and layout grids (columns, rows or a square grid) help you line things up. Layers snap to guides and grid edges. Runtimes ignore all of them.


---

# Style, tokens and fonts

> Fills, gradients, image fills, borders, shadows, blur, text styles, color tokens and embedded fonts in Envy, and how each maps to Godot and CSS.

Source: https://envyui.com/docs/style

## Paint

Frames, buttons and shapes have a **fill** (a color or a `$token`), or a linear or radial **gradient** instead. An **image fill** paints an image over that, clipped to the corners, as cover, contain, stretch or tile.

On top of the main fill, frames and buttons can stack **extra fills** and **extra strokes**, each with its own opacity, drawn under the children.

| Property | Notes |
|---|---|
| `radius` | Per corner |
| `border` | Drawn inside the layer, never affects layout |
| `shadow` | x, y, blur, color |
| `innerShadow` | x, y, blur, spread, color; above the fill, below the children |
| `backdropBlur` | Blurs what is behind the layer (frosted glass) |
| `layerBlur` | Blurs the layer itself and its children |
| `opacity`, `clip` | Group opacity and clipping |

In Godot, paint becomes a `StyleBoxFlat`; gradients, shapes and blurs are drawn by the addon's paint and shader code. See [known differences](/docs/differences) for the small places the two runtimes differ.

## Color tokens

Every color can be a token: write `$ember` instead of `#f2a24e`. Change the token and every layer that uses it follows, on every screen. Theme presets in the [starter kit](/kit) are sets of token values.

## Text

Text layers have content, font, size, weight, color, alignment, line height, letter spacing, wrapping, uppercase, an outline and a shadow. In Godot they become a `Label` with `LabelSettings`.

**Text styles** are shared typography (Display, Title, Button, Body…). A layer that uses a style follows it, so changing one style restyles every screen.

Text can include data: `HP {player.hp} / {player.hpMax}` updates as the game sets data. See [Data and events](/docs/data).

## Fonts

Envy has the whole Google Fonts catalog in its font picker. For the game, **embed** the fonts you use: the font files travel inside the document, and both runtimes use them with no setup.

- On the web, the runtime registers each embedded font directly, so a strict content security policy can't block it.
- In Godot, `EnvyUI` builds a `FontFile` for each embedded face. An entry in `EnvyUI.fonts` for the same family still wins.

The Last Hunt embeds Jaini, Archivo at two widths and Spectral Italic.

## Shapes

Ellipse, polygon, star, line and **path**. Draw paths with the pen tool (N): click for corners, drag for curves, then edit points. Closed paths are filled and stroked, open paths are stroked. Both runtimes draw the same geometry.


---

# Components

> Components, instances, variants, overrides and component properties in Envy. Build a button once and keep every copy on every screen in step.

Source: https://envyui.com/docs/components

A **component** is a board whose layers define a reusable piece: a button, a menu item, an item slot. An **instance** is a copy of it on a screen. Edit the component and every instance follows.

## Create one

Select a layer and press **Ctrl Alt K**. The layer becomes a component board, and the original spot holds an instance of it.

## Variants

Components that belong to the same **set** and differ in variant values are **variants**: Primary, Secondary, Ghost and Danger buttons, in Default, Focus, Pressed and Disabled, at three sizes. The Last Hunt's Button set has 48 variants. Switch an instance between them from the inspector.

## Properties

Properties let an instance change what it's meant to change, in one field:

| Type | What it does |
|---|---|
| Text | Replaces `{prop.Label}` in the component's text layers |
| Toggle | Shows or hides target layers (a badge, a meta line, a glyph) |
| Instance swap | Swaps a nested instance for another component (a different glyph or icon) |

The Last Hunt's menu item has `Label`, `Meta` and `Show meta`. Its main menu sets them per item: Continue shows "Chapter III", New hunt hides its meta line.

## Overrides

Anything else can be overridden per instance: a layer's text, fill, visibility, image, states, click actions or bindings. Overrides are stored on the instance by the path of the layer inside the component, and survive changes to the component. **Reset** clears them; **Detach** (Ctrl Alt B) turns the instance into plain layers.

## Button states

Buttons have **hover**, **pressed** and **disabled** states, each a small patch: fill, border color, text color, opacity and scale. Keyboard and gamepad focus use the hover look, plus an optional focus ring. Preview each state on the canvas before any code exists.

## In the runtimes

Both runtimes expand instances before drawing, with the same algorithm (`resolve.ts` on the web, `envy_resolve.gd` in Godot). Layers inside an instance get ids like `instanceId/sourceId`, which animations can target.


---

# Data, events and lists

> Bind Envy layers to game data, emit named events from buttons, run actions without code, preview scenarios and repeat a row for every item in an array.

Source: https://envyui.com/docs/data

Your game and its UI agree on two things: **data paths** the UI reads, and **event names** the UI sends. That's the whole contract. Re-export the UI as often as you like and game code doesn't change.

## Bindings

Bind a layer property to a data path:

| Property | Example |
|---|---|
| `text` | `player.name` |
| `value`, `max` | Progress bars: `player.hp`, `player.hpMax` |
| `visible` | `hud.showCrit` (prefix with `!` to negate: `!store.any`) |
| `opacity` | `ui.fade` |
| `disabled` | `!shop.canAfford` |

Text layers can also use templates: `{player.hp} / {player.hpMax}`. A path the data doesn't have leaves the template visible, on purpose, so you notice.

From the game:

```gdscript
ui.set_data("player.hp", 48)
ui.merge_data({"boss": {"hp": 22, "antlers": 2}})
```

```js
ui.setData("player.hp", 48);
ui.setData({ boss: { hp: 22, antlers: 2 } });
```

## Sample data and scenarios

**Sample data** fills the canvas and preview before the game exists. **Scenarios** are named patches over it: Hunt start, Low health, Boss enraged. Pick one to see it on the canvas. The AI handoff renders every screen in every scenario, so the programmer sees the edge cases too. Runtimes never read scenarios.

## Events

A button's click can **emit** an event with an optional payload. Game code listens for the name, never for a particular button:

```gdscript
func _on_ui_event(event: String, payload: String) -> void:
	match event:
		"new_hunt": start_new_hunt()
		"buy": shop.buy(payload)
```

```js
ui.on("new_hunt", () => game.startHunt());
ui.on("*", (payload, event) => console.log(event, payload));
```

## Actions

A click runs a list of actions in order, no code needed:

| Action | Does |
|---|---|
| `emit` | Sends an event to the game |
| `goto` | Shows another screen (with the screen's transition, or its own) |
| `push` / `pop` | Opens a screen over this one, closes the top one |
| `play` | Plays an animation |
| `set` / `toggle` | Changes data, like `settings.subtitles` |

The Last Hunt's menu items emit `new_hunt` and then go to Character select, so the prototype clicks through and the game still gets its event.

## Lists

Bind a frame to an array and its **template** child is drawn once per item:

```json
"list": { "path": "store.items", "template": "<row id>", "key": "id" }
```

Inside the template, `item.x` and `{item.x}` refer to the current item, and `{index}` is its position. An emit payload like `{item.id}` tells the game which item was clicked. Items with a `key` keep their layers when the list is reordered. Lists can nest.

Preview a list empty, with a few items or with a hundred, using scenarios.


---

# Animation, transitions and overlays

> Keyframe animation in Envy with seven easing curves, screen transitions (fade, slide, scale) and overlay screens, identical in Godot and the browser.

Source: https://envyui.com/docs/animation

## The timeline

Open the timeline with **Alt T**. An animation belongs to a screen and has tracks of keyframes for a layer's `x`, `y`, `scale`, `rotation` and `opacity`. Values add to the layout: x and y move the layer, scale and opacity multiply, rotation adds.

Turn on **record**, move a layer, and the timeline writes the keyframe for you.

- **Autoplay** plays it when the screen opens (The Last Hunt's menu Intro).
- **Loop** repeats it (the breathing "Press any button").
- Or start it from a button's **Play** action, or from game code: `ui.play("Hit")`.

## Easing

Each key's ease shapes the segment after it: `linear`, `in`, `out`, `inOut`, `back`, `elastic`, `step`. The curves are the same functions in TypeScript and GDScript, so motion matches on both sides.

## Screen transitions

A screen can say how it appears when you go to it:

```json
"transition": { "type": "fade", "duration": 0.3 }
```

| Type | Effect |
|---|---|
| `fade` | The old screen fades out while the new one fades in |
| `slide` | Both move in a direction; the new screen enters from the opposite edge |
| `scale` | The new screen grows from 92% to 100% while fading in |

A `goto` or `push` action can override it, and so can code: `ui.goto("12 Pause", { transition: { type: "none" } })`. The old screen stays mounted but takes no input until the new one has arrived. On the web, transitions are skipped for people who ask their system for reduced motion.

## Overlays

`push` opens a screen over the current one: a pause menu over the HUD. Screens below keep their state, follow data and keep animating, but take no input until they're on top again. Focus moves into the overlay and comes back to the button that opened it. `pop` closes the top screen. The overlay's own background is what dims the screen below, so give it a semi-transparent fill.

```gdscript
ui.push("12 Pause")
ui.pop()
```


---

# Keyboard and gamepad focus

> Make Envy menus playable with arrow keys, a d-pad or a stick. Automatic focus by position, explicit neighbours, initial focus and focus rings in Godot and the web.

Source: https://envyui.com/docs/focus

Every button can take keyboard and gamepad focus in both runtimes. With nothing set, arrows and the d-pad move to the nearest button in that direction. Set neighbours when the layout needs something else.

```json
"focus": {
  "down": "<button id>", "up": "<button id>", "left": "…", "right": "…",
  "next": "…", "prev": "…",
  "initial": true,
  "ring": { "color": "$ember", "width": 1, "offset": 0 }
}
```

- **Arrows, d-pad, left stick** go to `up`, `down`, `left`, `right`, else to the nearest button by position.
- **Tab and Shift Tab** follow `next` and `prev`, else the natural order.
- **initial** focuses that button when the screen opens. An overlay's initial button wins; closing the overlay returns focus to the button that opened it.
- **ring** draws an outline while a button has keyboard or gamepad focus, not after a mouse click. The hover look applies on focus too.
- A neighbour that's disabled or hidden is skipped.

In the editor, the compass in the inspector picks neighbours from the buttons on the screen, and document checks flag a neighbour that doesn't exist, isn't a button or sits on another screen.

## Runtimes

- **Web:** keys work on the focused button. Gamepads are read with the Gamepad API: d-pad or left stick move (held directions repeat), **A** presses, **B** closes the top overlay. Pass `gamepad: false` to turn it off.
- **Godot:** neighbours become `focus_neighbor_*`, `focus_next` and `focus_previous`; unset directions use Godot's own search. `ui_accept` presses and `ui_cancel` (Escape, gamepad B) closes the top overlay. Call `ui.focus_first_button()` to start navigation.

Try it on the [home page](/#new-focus): click the menu and use the arrow keys.


---

# Localization

> Translate an Envy game UI with keyed text and per-language tables, preview a pseudo-locale to catch clipping, export CSV for translators and switch language at runtime.

Source: https://envyui.com/docs/localization

A text layer opts into translation with a **key**. Its content is the text in the base language; tables hold the other languages.

```json
"i18n": {
  "base": "en",
  "tables": {
    "de": { "title.press": "Beliebige Taste drücken" },
    "fr": { "title.press": "Appuyez sur une touche" }
  }
}
```

```json
"text": { "content": "Press any button", "key": "title.press" }
```

- Translations can use data templates like `{player.name}` and list templates like `{item.name}`.
- A missing translation shows the base text.
- Locales match exactly first, then by language: `de-AT` finds `de`, `pt` finds `pt-BR`.
- **pseudo** shows accented text about 35% longer than the base, so you find clipping before real translations arrive.

## In the editor

The Data panel's Languages tab adds locales, shows a table per locale and generates keys for all text. Export CSV for translators and import it back. The canvas and preview can show any locale or the pseudo-locale, and typing on the canvas while a locale is shown edits that translation.

## At runtime

```gdscript
ui.locale = TranslationServer.get_locale()
ui.set_locale("de")
```

```js
const ui = Envy.mount(host, doc, { locale: navigator.language });
ui.setLocale("fr");
```

Switching rebuilds the open screens in place and keeps data, overlays and focus. The Last Hunt's title screen is translated into German, French, Spanish and Brazilian Portuguese; switch language in the [live demo](/#play).

Text that shows a component property (`{prop.Label}`) isn't translated by key: translate the value the instance sets instead.


---

# Handoff and export

> Export an Envy game UI as a Godot package, playable HTML, the raw document or an AI handoff package with AGENTS.md, a contract, screenshots and typed code.

Source: https://envyui.com/docs/handoff

Press **Ctrl E** to export. Export checks the document first and tells you what's wrong before you send anything.

| Export | What you get |
|---|---|
| Godot package | A zip with the `envy_ui` addon, your document and a demo scene. Open it in Godot and press F6 |
| Playable HTML | One HTML file with the runtime and your document. Anyone can click through it in a browser |
| AI handoff | Everything a programmer or a coding agent needs to wire the UI into a game (below) |
| Document | The `.envy.json` file itself |
| PNG | A layer or a screen as an image |

## The AI handoff package

`<name>_handoff.zip` contains:

| File | Purpose |
|---|---|
| `AGENTS.md`, `CLAUDE.md` | Instructions for coding agents: rules, files, integration steps for Godot and the web, the full event and data contract, and an acceptance checklist |
| `PROMPT.md` | Ready-to-paste prompts for Godot and for the web |
| `SCREENS.md`, `screens/` | A layer outline of every screen (text, bindings, actions, notes) and reference renders, also one folder per scenario |
| `contract.json` | Events (with the layers that emit them), data paths (type, sample, where they're used), screens, animations and scenarios |
| `godot/<name>_ui.gd`, `godot/addons/envy_ui/` | A generated controller with typed setters and an event `match`, and the runtime |
| `web/<name>-ui.ts`, `web/envy-runtime.js` | A typed wrapper (unions of events, screens and paths) and the runtime |
| `schema/envy.schema.json`, `tools/envy.mjs` | So agents can edit the document safely and validate it |

The rule the package teaches: load the document with the runtime and never rebuild screens by hand. Game code only connects data and events.

## What the generated code looks like

For The Last Hunt, the controller has a setter per data path and a case per event:

```gdscript
## boss.hp — shown in 09 HUD · Boss fight › Boss › bar › Boss health
func set_boss_hp(value: float) -> void:
	ui.set_data("boss.hp", value)

func _on_ui_event(event: String, payload: String) -> void:
	ui_action.emit(event, payload)
	match event:
		"new_hunt":
			# From: 02 Main menu › Main menu › Items › New hunt
			pass  # TODO
```

The TypeScript wrapper turns the same contract into types, so a typo in an event name is a compile error.

## Without the editor

The [CLI](/docs/cli) writes the same text files from a document: `node tools/envy.mjs handoff ui.envy.json out/`.

## Notes for implementers

Any layer can carry **notes**: what it's for, how it should behave, edge cases. They're included in SCREENS.md and AGENTS.md, so intent travels with the design.


---

# Godot runtime

> Run Envy game UI in Godot 4.3+ with the EnvyUI node. Real Control nodes, data binding, events, animation, overlays, translations and hot reload while the game runs.

Source: https://envyui.com/docs/godot

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

1. Copy `addons/envy_ui` into your project (it's in every Godot package and AI handoff export) and enable **Envy UI** in Project Settings › Plugins.
2. 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.
3. Add an `EnvyUI` node and set its document, or create it from code.

```gdscript
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](/docs/differences) for where Godot and the web draw slightly differently.


---

# Web runtime

> Run Envy game UI in any web page or web game with one dependency-free script. Mount a document, set data, listen to events, run overlays and switch language.

Source: https://envyui.com/docs/web

The web runtime is one script with no dependencies. It renders a document to plain DOM elements and runs it: states, data, events, animation, transitions, overlays, focus and translations. The editor's canvas uses the same renderer.

## Install

```html
<div id="ui" style="position: fixed; inset: 0"></div>
<script src="envy-runtime.js"></script>
<script type="module">
  const doc = await fetch("ui/my_ui.envy.json").then((r) => r.json());
  const ui = Envy.mount(document.getElementById("ui"), doc, { screen: "Main Menu" });
  ui.on("start_game", () => game.start());
  ui.setData("player.hp", 40);
</script>
```

`envy-runtime.js` defines a global `Envy`. It comes with every web and AI handoff export. In a bundled game, the generated TypeScript wrapper (`web/<name>-ui.ts`) gives you typed events, screens and data paths.

## Options

| Option | Default | Meaning |
|---|---|---|
| `screen` | First screen | Screen to show first, by name or id |
| `data` | Sample data | Initial data |
| `locale` | Base text | Locale for translated text, or `"pseudo"` |
| `scaleMode` | `"fit"` | Scale the design resolution into the element, or `"none"` |
| `autoplay` | `true` | Play autoplay animations when a screen shows |
| `gamepad` | `true` | Gamepad navigation |
| `respectReducedMotion` | `true` | Skip screen transitions for reduced motion |
| `onEvent`, `onScreenChange`, `onDataChange` | | Callbacks |

## The player

| Member | Does |
|---|---|
| `goto(screen, { transition })` | Shows a screen |
| `push(screen)`, `pop()`, `stack` | Overlays |
| `setData(path, value)`, `setData(patch)`, `getData(path)` | Data |
| `play(anim)`, `stop(anim)`, `isPlaying(anim)` | Animations |
| `setLocale(locale)`, `locales`, `locale` | Language |
| `on(event, fn)`, `off(event, fn)`, `emit(event, payload)` | Events (`"*"` listens to all) |
| `layout()`, `destroy()` | Rescale after a resize you manage, unmount |

## Security

The runtime treats a document as data. Colors are validated, stroke markup is built with DOM calls instead of HTML strings, and embedded fonts load only from `data:` URLs or same-origin paths, so a document can't make the page fetch fonts from other origins.

## Size

The runtime is small enough to ship with a menu: see the [runtimes page](/runtimes) for the current size.


---

# CLI

> The envy command-line tool validates Envy documents in CI, prints the event and data contract, outlines screens, writes handoff files and prints the JSON Schema.

Source: https://envyui.com/docs/cli

`tools/envy.mjs` is a single Node.js file. It ships in every AI handoff package, so agents and CI can use it without the editor.

```sh
$ node tools/envy.mjs validate ui/my_ui.envy.json
0 error(s), 0 warning(s) — 24 screens, 180 components, 6098 layers
```

## Commands

| Command | Does |
|---|---|
| `envy validate <file> [--json]` | Checks references and contracts. Exits with 1 on errors, so it can gate CI |
| `envy describe <file> [--screen "Name"]` | Markdown outline of screens: text, bindings, actions |
| `envy contract <file>` | Events, data paths, screens and animations as JSON |
| `envy prompt <file> [--engine godot\|web]` | A prompt for an AI coding assistant |
| `envy handoff <file> <out-dir>` | Writes AGENTS.md, SCREENS.md, contract.json and code stubs |
| `envy schema` | The JSON Schema of the document format |

## In CI

```yaml
- run: node tools/envy.mjs validate ui/my_ui.envy.json
```

A failing check stops the build before a broken UI reaches players.

## What validate checks

Missing children, parents, components, assets, tokens, screens and animations; invalid colors; empty or unsafe event names; focus targets that aren't buttons or sit on another screen; component properties with the wrong type or a missing target; translation keys that are invalid, missing or unused; and data paths with no sample value.


---

# For AI coding agents

> How AI coding agents work with Envy - the AI handoff package, the event and data contract, the JSON Schema, the CLI, llms.txt and Markdown docs.

Source: https://envyui.com/docs/agents

Envy is built so a coding agent can wire a UI into a game without guessing. This page is for people who work with agents, and for the agents themselves.

## If you are an agent

1. Read `AGENTS.md` in the handoff package first. It lists the files, the rules, the integration steps for Godot and the web, and the acceptance checklist.
2. **Load the document with the runtime. Never rebuild screens by hand.** The `.envy.json` file is the UI.
3. Your job is the integration: set data with `set_data` / `setData`, and handle the events in `contract.json`.
4. Check your work against `screens/` (one render per screen, and per scenario).
5. If you edit the document, validate it: `node tools/envy.mjs validate <file>`. The JSON Schema is in `schema/envy.schema.json`.

## What agents get

| Source | Use it for |
|---|---|
| [AI handoff package](/docs/handoff) | Everything for one UI: instructions, contract, renders, typed code, runtime, schema, CLI |
| `contract.json` | Every event (and the layer that emits it) and every data path (type, sample, where it's used) |
| [CLI](/docs/cli) | `validate`, `describe`, `contract`, `prompt`, `handoff`, `schema` |
| [/llms.txt](/llms.txt) | An index of these docs for language models |
| [/llms-full.txt](/llms-full.txt) | All docs in one plain-text file |
| `/docs/<page>.md` | Each docs page as Markdown, for example [/docs/data.md](/docs/data.md) |

## Coming next

<span class="tag-planned">Planned</span> An **MCP server** so agents read and edit documents through tools (read an outline, get a node, patch it with validation, add a screen, list the contract, render a screen) instead of editing raw JSON. You review each change in Envy before it lands.


---

# The document format

> Reference for the .envy.json game UI document - boards, nodes, layout, style, components, interaction, bindings, focus, lists, scenarios, localization and animation.

Source: https://envyui.com/docs/format

An Envy document is one JSON file (`*.envy.json`). Both runtimes read it as is. Missing fields are filled with defaults on load, so hand-written documents stay short. The JSON Schema is available from `envy schema`.

```json
{
  "format": "envy-ui", "version": 2, "id": "d_…", "name": "My game UI",
  "description": "What this UI is for, read by implementers and AI agents",
  "tokens": { "colors": { "accent": "#f2c14e" } },
  "textStyles": { "H1": { "font": "Rajdhani", "size": 56, "weight": 700, "lineHeight": 1.05, "letterSpacing": 6, "uppercase": true } },
  "assets": { "img_…": { "name": "…", "src": "data:image/png;base64,…", "width": 512, "height": 512 } },
  "screens": [ { "id": "…", "name": "Main Menu", "root": "<node id>", "width": 1920, "height": 1080 } ],
  "components": [ { "id": "…", "name": "Button / Primary", "root": "<node id>", "set": "…", "variant": { "Style": "Primary" } } ],
  "componentSets": [ { "id": "…", "name": "Button", "props": [ { "name": "Style", "values": ["Primary", "Danger"] } ] } ],
  "nodes": { "<id>": { } },
  "animations": [ ],
  "sampleData": { "player": { "hp": 72 } },
  "scenarios": [ { "id": "…", "name": "Low health", "data": { "player": { "hp": 5 } } } ],
  "i18n": { "base": "en", "tables": { "de": { "menu.play": "Spielen" } } }
}
```

## Boards and nodes

Screens and components are both **boards**: a root node with no parent. Nodes live in one flat map and form a tree through `parent` and `children`; children order is paint order.

Node types: `frame`, `button`, `text`, `image`, `progress`, `shape`, `instance`. Frames and buttons have children; instances get theirs from their component. Any node can carry `notes`.

| Field | See |
|---|---|
| `layout` (anchors, offsets, width, height, sizing, rotation) | [Layout](/docs/layout) |
| `container` (mode, gap, padding, align, justify, wrap) | [Layout](/docs/layout) |
| `style`, `text`, `image`, `progress`, `shape` | [Style](/docs/style) |
| `instance` (component, overrides, values) | [Components](/docs/components) |
| `states`, `events.click` | [Components](/docs/components), [Data and events](/docs/data) |
| `bindings`, `list` | [Data and events](/docs/data) |
| `focus` | [Focus](/docs/focus) |
| `text.key` | [Localization](/docs/localization) |

## Colors

A color is `#rrggbb`, `#rrggbbaa` or a token reference like `$accent`.

## Animations

```json
{ "id": "…", "name": "Intro", "screen": "<screen id>", "duration": 1.4, "loop": false, "autoplay": true,
  "tracks": [ { "id": "…", "node": "<node id>", "prop": "opacity", "keys": [ { "t": 0, "v": 0, "ease": "out" }, { "t": 0.5, "v": 1, "ease": "linear" } ] } ] }
```

See [Animation](/docs/animation).

## Versions

The format has a version number, and older documents load through a migration step (`normalizeDoc`). Documents from version 1 and the older `strata-ui` id load unchanged.


---

# Known differences

> Where Envy's Godot and web runtimes draw or behave slightly differently - fonts, clipping, shadows, blur, group opacity, focus search and lists.

Source: https://envyui.com/docs/differences

Both runtimes read the same document and share their layout, component, animation and geometry rules. A few things are drawn by each engine's own tools, and differ slightly.

| Area | Web | Godot |
|---|---|---|
| Fonts not embedded | Google Fonts by family name | `EnvyUI.fonts` mapping, else a SystemFont with that name |
| Rounded clipping | Always clips to the rounded corners | `clip_children` when the frame has a visible fill, otherwise a rectangle |
| Drop shadows | CSS blur | StyleBoxFlat `shadow_size`, about blur × 0.6; shapes have no shadow yet |
| Inner shadow | `box-shadow: inset`, border on top | A shader, border underneath |
| Extra fills and strokes | A layer stack inside the node | Two canvas items under the children; a button's hover border color doesn't apply while it has extra fills or strokes |
| Layer blur | `filter: blur()` on the layer | Blurs a screen copy of the layer's area, so content behind a translucent layer is blurred too |
| Background blur | `backdrop-filter` | A screen-texture shader, a little softer at large radii; only blurs what was drawn earlier on the same canvas layer |
| Group opacity | The group is flattened | `modulate` multiplies each child, visible where children overlap |
| Large corner radii | Smooth | Slightly faceted (StyleBoxFlat corner detail tops out at 20) |
| Focus search | Nearest button by position | Godot's own search; unusual layouts can pick a different neighbour |
| Escape and overlays | Escape doesn't close overlays (gamepad B does) | `ui_cancel` (Escape, B) closes the top overlay |
| Lists | Re-expanded on every data change, elements reused by id | Rebuilt only when item keys or order change; other changes update in place |

Embedded fonts, layout, anchors, auto layout, components, properties, bindings, events, transitions, overlays, translations and easing behave the same in both.