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.
  • chunk_load_radius: number of chunk rings around the player that should be loaded immediately. Default: 2.
  • chunk_prefetch_radius: wider background streaming radius around the player. Chunks outside this radius are unloaded. Default: 5.
  • chunk_build_budget_near: max chunk builds per frame while near chunks are still missing. Higher values reduce startup wait but can cost frame time. Default: 10.
  • chunk_build_budget_far: max chunk builds per frame after near chunks are loaded (background streaming). Default: 2.

On startup, chunks around the player are built first. Farther chunks inside chunk_prefetch_radius are streamed in later.

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
chunk_load_radius = 2
chunk_prefetch_radius = 5
chunk_build_budget_near = 10
chunk_build_budget_far = 2

[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.
  • spell - Spell template name used when intent = "spell". Clicking a character casts that spell at the clicked target.
  • 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"

Example 4​

Spell intent button.

  • In 3D, select it and click a character to cast at that target.
  • In 2D, select it and cast via directional intent input (like other directional intents such as look).
[ui]
role = "button"
intent = "spell"
spell = "Fireball"
deactivate = ["LookIntent", "UseIntent", "PickupIntent", "DropIntent"]
border_size = 1
border_color = "#ffff88"

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}, {PLAYER.LEVEL}, {PLAYER.EXP}, {PLAYER.ATTACK}, and {PLAYER.ARMOR} are replaced at runtime.
  • tab_width: optional tab stop width in pixels for \t alignment inside the text.
  • 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.

Combat-related player placeholders:

  • PLAYER.ATTACK is the accumulated DMG value across the player's equipped weapon slots.
  • PLAYER.ARMOR is the accumulated ARMOR value across the player's equipped gear slots.
  • PLAYER.LEVEL resolves through game.level.
  • PLAYER.EXP and PLAYER.EXPERIENCE resolve through game.experience.
  • PLAYER.WEAPON.<ATTR> sums an attribute across the player's weapon slots.
  • PLAYER.EQUIPPED.<ATTR> sums an attribute across all equipped items.
  • PLAYER.ARMOR.<ATTR> sums an attribute across the player's gear slots.

The slot groups come from game.weapon_slots and game.gear_slots in Game / Settings.

Example​

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

STR:\t{PLAYER.STR}\tDEX:\t{PLAYER.DEX}
EXP:\t{PLAYER.EXP}\tLEVEL:\t{PLAYER.LEVEL}
HP:\t{PLAYER.HP}\tG:\t{PLAYER.FUNDS}
ATK:\t{PLAYER.ATTACK}\tDEF:\t{PLAYER.ARMOR}

May the stars guide you!
"""

font = "Tiny5-Regular"
font_size = 18.0
spacing = 2.0
tab_width = 110.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