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.

Say Section​

Use [say] on a game widget to style speech bubbles produced by say(...). These settings are presentation-specific, so different game widgets can use different bubble colors or backgrounds.

[say]
duration = 1.0                 # How long say bubbles stay visible, in in-game minutes.
default = "#E5E501"            # Default text color when category is empty or unknown.
background_enabled = true      # Draw a background rectangle behind say text.
background_color = "#00000080" # Background RGBA color (#RRGGBBAA).

# Optional per-category text colors:
npc = "#FFFFFF"
warning = "#FF6666"
quest = "#66CCFF"
  • duration: Lifetime of a say(...) bubble in in-game minutes. The runtime uses the first active game widget duration and falls back to 1.0.
  • default: Fallback text color for say("Text") or unknown categories.
  • background_enabled: Enables or disables the bubble background rectangle.
  • background_color: Background color including alpha, for example #00000080 for 50% black.
  • Category keys: Any extra key in [say] is treated as a text color category used by say("Text", "category_name").

Legacy projects with global game-config [say] still work as a fallback, but new projects should keep this section on the game widget.

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"

[say]
default = "#E5E501"
warning = "#FF6666"
background_enabled = true
background_color = "#00000080"
[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 assigned through the Tile Picker dock.

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.
  • party - Optional UI binding target for this widget. If omitted, Eldiron uses the current leader for backward compatibility. Supported values today are leader, party.0, party.1, ... and named bindings that match a character's party_role or name.
  • portrait - If true, the button draws the bound character's portrait_tile_id instead of an inventory/equipped item.
  • 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 let intent buttons show specific mouse cursors when hovering or clicking an entity or item. They work in 3D, and also in 2D when [game].click_intents_2d = true:

  • 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​

Buttons that represent inventory_index or equipped_slot automatically enable drag-and-drop unless you explicitly set drag_drop = false.

  • 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).
  • World items can also be dragged directly into slot widgets.
  • Dragging an owned item out of a slot and onto terrain drops it into the world.
  • Slot widgets can bind to different party members using party.
[ui]
role = "button"
inventory_index = 0
party = "leader"
[ui]
role = "button"
equipped_slot = "main_hand"
party = "party.1"
[ui]
role = "button"
portrait = true
party = "leader"

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"
# party = "leader"
# inventory_index = 0
# equipped_slot = "main_hand"
# portrait = true
# 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 bound character avatar is used.
  • party - Optional binding target for the avatar widget. If omitted, Eldiron uses the current leader.
  • 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"
party = "leader"
# avatar = "Human"
animation = "Idle"
frame_index = 0
# perspective = "front"
# show_weapons = true

Party Binding​

Screen widgets that show character-related content can bind to a party target with ui.party.

Supported values today:

  • leader - the default binding used by existing projects
  • party.0, party.1, ... - bind by party index
  • a character party_role
  • a character name

This system is intentionally expandable. Current projects continue to work because omitted party still resolves to the leader/current player path.

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
message_spacing = 8
warning = "#ff8888"
default = "#ffffff"

Use handles to decide which message/choice streams a Messages widget displays. This lets you place one Messages widget as a log and another as a dialog overlay on top of the game view.

[ui]
role = "messages"
handles = ["dialogs"]
top_down = true

Supported handles are:

  • messages: Regular message(...) output.
  • dialogs: TOML-authored dialog(...) text and choices.
  • multiple_choice: Script-authored multiple_choice(...) prompts and choices.
  • offer_inventory: Vendor inventory offers from offer_inventory(...).

If handles is omitted, the widget displays all streams.

Messages widgets can optionally draw the sender character's existing portrait_tile_id on the left and wrap text to the right. This works for regular messages, dialogs, script multiple-choice menus, and inventory offers.

[ui]
role = "messages"
handles = ["dialogs"]
portrait = true
portrait_size = 64
portrait_gap = 12

Layout Notes​

  • spacing: vertical spacing between wrapped lines inside one message block
  • message_spacing: vertical spacing between separate message blocks
  • portrait_size: square portrait size in pixels when portrait = true
  • portrait_gap: horizontal spacing between the portrait and text

This is useful when long wrapped messages would otherwise run visually into the next message.

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