UI cards

UI cards are your 2D interface: HUDs, menus, buttons, labels and dialogue. This page shows how to place a card and connect it to your scene.

A card is laid out like a normal app screen, in front of the 3D view. So its text stays sharp at any distance and on any screen size. Text on a plane in the 3D world depends on where the camera is, so use a card for anything people need to read.

A card is a file in your project, and you attach it to an object.

Add a card to an object

1. Select the object.
2. In the inspector, click + new component and choose UI.
3. Pick the card in Select a UI.
4. Choose Overlay or Anchored.
5. Click Edit layout to design the card in the UI editor.

To work on the interface of the whole scene, click Scene UI in the left rail. How to use the editor is in UI editor.

Overlay or anchored

Overlay fills the screen. Use it for a HUD, a menu or a dialogue box.

Anchored pins the card to an object's position on screen. Use it for a name over a character or a price over a product.

An anchored card keeps its size

It stays the size you designed, and hides when its object goes behind the camera. It is a label attached to something, not an object in the world. If you want something that gets smaller as people walk away, use 3D text.

What you can build with

A card is made of these building blocks:

container · text · image · gif · video · separator · grid · gallery
pager · tabs · state · indicator · slider · input · select · switch

Make a button from text or a container

There is no separate button block. A button is a text or a container with a background, some padding, a border and an action. So your button looks exactly the way your design needs.

• Templates. For anything that repeats, like a row in a list, a chip or a card in a gallery, build a template once and reuse it.
• Screens. A card can have several screens and switch between them on its own, without the scene. Use this for a panel with tabs or a dialogue with several steps.

Custom components and third-party extensions, such as Lottie, do not show.

Make a card do something

A card has its own variables. It can use them to change itself: show and hide parts, swap text, switch screens, run timers. Keep anything that is only about the interface inside the card.

When the card needs to affect the scene, there are three ways, from simplest to most flexible:

Way	Use it for
A built-in card action	interface changes only: a tab, a toggle, a timer
A scene step on the action	running a scene step without code: switch scene, play an animation
A named action and a script	game logic

An action on a card also sends an event up through the object's parents. So an event on the scene can catch a press on any card inside it. Use the UI action trigger and set Action id to react to one button, or leave it empty to react to any press.

A script can read a card's variables, change them, and listen for presses:

const ui = ctx.getDivKit(entity);

ui.set('score', (v) => v + 1);
ui.subscribe('lives', (v) => {
  /* the display changed */
});
ui.onAction('restart', () => {
  /* the restart button was pressed */
});

Keep the game state in the script, and let the card show it. Not the other way round.

Images and video in a card

Inside a card, point at a file from your project, not at a URL. This also works inside expressions, so you can pick an image based on a condition.

Before you start designing

• A card shows only while its scene is active, so interface never carries over between scenes.
• A screenshot of the 3D view does not include your cards. Check your interface in preview.
• Card variables are not shared between people in the same session, and they reset when the page reloads. Anything that must be shared or kept belongs in a script.
• The visual editor shows a selected set of properties. Layouts written by hand stay as they are when you edit the card, but they have no properties panel.

---

Next: Material graphs — build your own material when the standard ones are not enough.