Widgets

Widgets are the visual building blocks of Two-Face. Each widget type displays a specific kind of game information.

Overview

Two-Face provides these widget types:

Widget	Type	Purpose
Text Window	`text`	Scrollable game text
Tabbed Text	`tabbed_text`	Multiple streams in tabs
Command Input	`command_input`	Command entry field
Progress Bar	`progress`	Health, mana, etc.
Countdown	`countdown`	RT, cast time
Compass	`compass`	Available exits
Hand	`hand`	Items in hands
Indicator	`indicator`	Status conditions
Injury Doll	`injury_doll`	Body injuries
Active Effects	`active_effects`	Buffs/debuffs
Room Window	`room`	Room description
Inventory	`inventory`	Item list
Spells	`spells`	Known spells
Dashboard	`dashboard`	Composite status
Performance	`performance`	Debug metrics

Common Properties

All widgets share these properties in layout.toml:

Identity

[[windows]]
name = "my_widget"     # Unique identifier (required)
type = "text"          # Widget type (required)

Position

# Grid-based positioning
row = 0                # Row (0 = top)
col = 0                # Column (0 = left)

# OR pixel positioning
x = 100                # X coordinate
y = 50                 # Y coordinate

Size

# Fixed size
width = 40             # Columns wide
height = 10            # Rows tall

# OR percentage
width = "50%"          # Half of layout width
height = "100%"        # Full layout height

Borders

show_border = true           # Display border
border_style = "rounded"     # Style: plain, rounded, double, thick
border_sides = "all"         # Which sides: all, none, top, bottom, etc.
border_color = "#5588AA"     # Border color

Title

show_title = true            # Show title bar
title = "Custom Title"       # Override default title

Colors

background_color = "#000000" # Background
text_color = "#CCCCCC"       # Default text
transparent_background = false  # See-through background

Text Displays

Widgets that show game text:

Text Window - Main game output, speech, thoughts
Tabbed Text - Multiple streams in one widget
Room Window - Room name, description, exits

Status Displays

Widgets that show character status:

Progress Bar - Health, mana, stamina, spirit
Countdown - Roundtime, cast time
Hand - Left hand, right hand, spell
Indicator - Stunned, hidden, webbed, etc.
Injury Doll - Body part injuries
Active Effects - Spells, buffs, cooldowns

Widgets for game navigation:

Compass - Available exits with directions

Lists

Widgets that display lists:

Inventory - Items carried
Spells - Known spells

Composite

Widgets combining multiple elements:

Dashboard - Configurable status panel

Debug

Developer/debugging widgets:

Performance - Frame rate, memory, network stats

Stream Mapping

Text-based widgets receive data from game streams:

Stream	Content	Default Widget
`main`	Primary game output	Main text window
`speech`	Player dialogue	Speech tab/window
`thoughts`	ESP/telepathy	Thoughts tab/window
`combat`	Combat messages	Combat tab/window
`death`	Death messages	Death window
`logons`	Login/logout	Arrivals window
`familiar`	Familiar messages	Familiar window
`group`	Group information	Group window
`room`	Room data	Room window
`inv`	Inventory data	Inventory window

Configure stream mapping in layout:

[[windows]]
name = "my_window"
type = "text"
stream = "speech"    # Display speech stream

Creating Custom Layouts

Combine widgets to create your ideal interface:

[layout]
columns = 120
rows = 40

# Main game text (left side)
[[windows]]
name = "main"
type = "text"
row = 0
col = 0
width = 80
height = 35

# Channels on right
[[windows]]
name = "channels"
type = "tabbed_text"
tabs = ["speech", "thoughts", "combat"]
row = 0
col = 80
width = 40
height = 20

# Status area
[[windows]]
name = "health"
type = "progress"
stat = "health"
row = 20
col = 80
width = 40
height = 1

# Command input at bottom
[[windows]]
name = "input"
type = "command_input"
row = 38
col = 0
width = 120
height = 2

Focus

Click a widget to focus it
Use Ctrl+Tab to cycle focus
Focused widget has highlighted border

Scrolling

Page Up / Page Down - Scroll focused text widget
Mouse wheel - Scroll widget under cursor
Home / End - Jump to top/bottom

Selection

Click and drag to select text
Ctrl+C to copy selection
Double-click to select word

Performance Considerations

Buffer Sizes

Text widgets buffer a limited number of lines:

[[windows]]
name = "main"
type = "text"
buffer_size = 2000    # Max lines (default)

Larger buffers use more memory. Reduce for secondary windows.

Each widget has rendering overhead. For performance:

Use tabbed windows instead of multiple text windows
Disable unused widgets
Reduce buffer sizes on secondary windows

Two-Face Documentation