Skip to main content

Widgets

Widget Drawing Order​

Every widget supports a layer index attribute in its ui section, higher layer values are drawn later. Except the game widget which is always drawn first. The default layer value is 0.

[ui]
layer = 1

Game Widgets​

Use a widget with role = "game" to render the game inside a screen. The game layer is always drawn first and the other widgets on top of it.

UI Section​

  • role = "game" draws the game output into this widget region.
  • grid_size (2D): pixel size of one tile (zoom level); if omitted, it falls back to [viewport].grid_size.
  • upscale (3D): render at (widget size ÷ upscale) and scale back up; 1 keeps native size, higher values soften, lower values sharpen.

Camera Section​

  • type: Rendering camera mode; iso, firstp, or 2D.
  • azimuth (iso, optional): horizontal rotation in degrees. If omitted, camera default is used.
  • elevation (iso, optional): vertical angle in degrees. Higher values look more top-down and help seeing inside buildings. If omitted, camera default is used.
  • scale (iso, optional): orthographic half-height (zoom). Larger values zoom out. If omitted, camera default is used.

Legacy aliases are still accepted for compatibility: azimuth_deg, elevation_deg.

player input controls

This setting only affects rendering. It does not change how player input controls the camera.
To define player camera behavior, see set_player_camera.

Examples​

[ui]
role = "game"
grid_size = 40
upscale = 1.5

[camera]
type = "firstp"
[ui]
role = "game"
grid_size = 40

[camera]
type = "iso"
azimuth = 135.0
elevation = 50.0
scale = 6.0

Button Widgets​

Button widgets define interactive UI elements that trigger game actions, intents or other logic when clicked.

Buttons are visually styled using the tiles defined by the Apply Tile action.

In the HUD you can select between two icons per sector:

  • The default (normal) state.
  • The active state is shown when the button is clicked or when its associated action is currently active.

UI Section​

  • action - Trigger a game action (mutually exclusive with intent).
  • intent - Send an intent such as "use"; empty string means walking intent.
  • inventory_index - Draw and interact with the inventory item at that slot using the intent.
  • equipped_slot - Draw and interact with the equipped item in that slot (for example main_hand, off_hand) using the intent.
  • drag_drop - Enable drag-and-drop interaction for this inventory/equipped slot button.
  • show / hide - Toggle specific widgets when clicked.
  • deactivate - Turn off other buttons when clicked.
  • active - Set this button’s state to active by default.
  • camera - Switch game widget rendering camera: 2d, iso, firstp.
  • player_camera - Switch player input mapping camera mode on the server: 2d, iso, firstp.
  • camera_target - Optional target game widget name; if omitted, applies to all game widgets.
  • border_size - An optional border for the button. Default size is 0 (no border).
  • border_color - The color for the border. Default is white ("#FFFFFF").

The following attributes are valid for 3D scenes only. They enable intent buttons to be able to show specific mouse cursors when hovering or clicking an entity or item:

  • entity_cursor_id - The tile id for the mouse cursor when hovering above a character.
  • entity_clicked_cursor_id - The tile id for the mouse cursor when clicking a character.
  • item_cursor_id - The tile id for the mouse cursor when hovering above an item.
  • item_clicked_cursor_id - The tile id for the mouse cursor when clicking an item.

Drag And Drop Slots​

Set drag_drop = true on buttons that represent inventory_index or equipped_slot to enable slot drag-and-drop.

  • Click/release on the same slot still triggers normal intent handling (for example look).
  • Dragging an item and releasing on another slot moves or swaps items.
  • Dropping onto an equipped slot is validated against the item's slot attribute.
  • Incompatible equipment drops are ignored (for example main_hand item into off_hand slot).
[ui]
role = "button"
inventory_index = 0
drag_drop = true
[ui]
role = "button"
equipped_slot = "main_hand"
drag_drop = true

Example #1​

In this example, clicking the button causes the player to move forward.

See the list of available actions here.

[ui]
role = "button"
action = "forward"
# intent = "talk"
# inventory_index = 0
# equipped_slot = "main_hand"
# border_size = 1
# border_color = "#888888"

Example 2​

This button:

  • Shows the widget with the sector name of Messages
  • Hides all widgets which starts with Inventory.
  • Deactivate the button named Show Inventory.
  • Sets its own state to active.
[ui]
role = "button"

show = ["Messages"]
hide = ["Inventory*"]

deactivate = ["Show Inventory"]

active = true

Example 3​

This button switches both rendering camera and player input mapping to first-person.

[ui]
role = "button"
camera = "firstp"
player_camera = "firstp"
# camera_target = "Game View"

Avatar Widgets​

Use a widget with role = "avatar" to render an avatar preview in the UI.

This uses the same avatar colorization pipeline as runtime avatars and can optionally include equipped weapons.

UI Section​

  • avatar - Avatar name to preview (for example "Human"). If omitted, the player avatar is used.
  • animation - Optional animation name (for example "Idle"). If omitted, the current avatar animation is used.
  • frame_index - Frame index to render (defaults to 0).
  • perspective - Optional direction: front, back, left, right (defaults to front).
  • show_weapons - Include equipped weapon overlays (true by default).

Example​

[ui]
role = "avatar"
avatar = "Human"
animation = "Idle"
frame_index = 0
# perspective = "front"
# show_weapons = true

Text Widgets​

Text widgets display text on the screen and can include static content or dynamic placeholders for player or game data.

UI Section​

  • text: multiline string content; placeholders like {PLAYER.STR}, {PLAYER.DEX}, {PLAYER.FUNDS} are replaced at runtime.
  • font: font family name.
  • font_size: size of the font.
  • spacing: line spacing.
  • color: text color.

You can customize the font, size, line spacing, and color of the text.

Example​

[ui]
role = "text"
text = """
Welcome, adventurer!

STR:  {PLAYER.STR}  DEX: {PLAYER.DEX}
GOLD: {PLAYER.FUNDS}

May the stars guide you!
"""

font = "Tiny5-Regular"
font_size = 18.0
spacing = 2.0
color = "#aaaaaa"

Messages Widget​

The Messages widget displays all incoming messages for the player in a scrollable list.

UI Section​

  • Messages are sent using the message command.
  • Each message can include an optional category to pick a display color.
  • If no category is specified, messages default to color #aaaaaa (override with default).

You can define custom colors for categories using keys in the widget's data section. In the example below, messages with the "warning" category will appear in light red.

By default, messages are listed bottom-up (most recent at the bottom). To change this to top-down, set top_down = true in the widget’s configuration.

Example​

[ui]
role = "messages"
font = "Tiny5-Regular"
font_size = 18.0
spacing = 5
warning = "#ff8888"
default = "#ffffff"

Multiple Choice​

For displaying multiple choice messages (for example when a vendor offers his inventory), there are two more options:

[ui]
column_width = 30 # The width of the body column of the text
multiple_choice = "#ffff88" # The color for multiple choice items