Two-Face

A modern, high-performance multi-frontend client for GemStone IV

What is Two-Face?

Two-Face is a feature-rich terminal client designed specifically for GemStone IV, the legendary text-based MMORPG by Simutronics. Built from the ground up in Rust, Two-Face delivers:

• 60+ FPS rendering with sub-millisecond event processing
• Fully customizable layouts with pixel-perfect window positioning
• Rich theming support with 24-bit true color
• Multiple connection modes (Lich proxy or direct eAccess authentication)
• Modern TUI built on ratatui with planned GUI support via egui

┌─────────────────────────────────────────────────────────────────────────┐
│                              Two-Face                                    │
│                                                                          │
│  ┌─────────────────────────┐  ┌────────────────────────────────────┐   │
│  │      Main Window        │  │         Room Description           │   │
│  │                         │  │  [Obvious exits: north, east, out] │   │
│  │  A goblin attacks!      │  └────────────────────────────────────┘   │
│  │  > attack goblin        │  ┌──────────┐  ┌──────────┐              │
│  │  You swing at a goblin! │  │ ◄ N ►    │  │ HP: 100% │              │
│  │                         │  │   S      │  │ MP:  87% │              │
│  └─────────────────────────┘  └──────────┘  └──────────┘              │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ >                                                                │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘

Philosophy

Two-Face is built on these core principles:

1. Performance First

Every design decision prioritizes smooth, responsive gameplay. Generation-based change detection, lazy text wrapping, and efficient memory management ensure Two-Face never gets in your way.

2. Customization Without Limits

Your client should look and behave exactly how you want. Every window can be positioned, sized, styled, and configured independently. Create layouts for hunting, merchanting, roleplaying, or anything else.

3. Modern Architecture

A clean separation between Core (game logic), Data (state), and Frontend (rendering) allows for multiple frontends (TUI today, GUI tomorrow) while keeping the codebase maintainable.

4. Developer Friendly

Written in idiomatic Rust with comprehensive documentation. Want to add a new widget type? Extend the parser? Create a custom browser? The architecture supports it.

Feature Highlights

Layouts

Design your perfect interface with TOML-based layout files. Position windows by row/column or pixel coordinates. Nest windows, create tabs, configure borders and colors per-window.

Highlights

Apply colors and styles to game text with regex patterns. Highlight creature names, player speech, spell effects, or anything else. Fast literal matching via Aho-Corasick for high-frequency patterns.

Keybinds

Bind any key combination to game commands, client actions, or macros. Full modifier support (Ctrl, Alt, Shift). Action-based system supports scrolling, navigation, text editing, and custom commands.

Themes

Complete color control with presets, palettes, and per-widget overrides. Ship with dark and light themes, or create your own.

Sound

Audio alerts for game events with configurable triggers. Text-to-speech support for accessibility.

Connection Modes

Connect via Lich for scripting integration, or directly authenticate with eAccess for standalone operation.

Quick Start

# Via Lich (default)
two-face --port 8000

# Direct connection
two-face --direct --account YOUR_ACCOUNT --character CharName

See Installation for detailed setup instructions.

Documentation Structure

This documentation is organized for multiple audiences:

Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• In-Game: Find us on the amunet channel

License

Two-Face is open source software. See the repository for license details.

Ready to dive in? Start with Installation.

Getting Started

Welcome to Two-Face! This section will guide you from installation to your first game session.

Overview

Getting Two-Face running involves three steps:

1. Installation - Download or build Two-Face for your platform
2. First Launch - Connect to GemStone IV
3. Quick Tour - Learn the essential controls

Prerequisites

Before you begin, ensure you have:

• A GemStone IV Account: Create one at play.net
• A Modern Terminal: Windows Terminal, iTerm2, or any terminal with 256+ color support
• Optional: Lich: For scripting support, install Lich

Connection Modes

Two-Face offers two ways to connect:

Lich Proxy Mode (Recommended for Script Users)

# Start Lich with your character, then:
two-face --port 8000

• Full Lich script compatibility
• Scripting and automation support
• Most users choose this option

Direct Mode (Standalone)

two-face --direct --account YOUR_ACCOUNT --character CharName --game prime

• No Lich dependency
• Authenticates directly with eAccess
• Ideal for lightweight setups

What’s Next?

Ready to install? Continue to Installation.

Installation

This guide covers installing Two-Face on all supported platforms.

Quick Install

Pre-built Binaries

Download the latest release for your platform from GitHub Releases:

Extract and Run

Windows:

# Extract to a folder
Expand-Archive two-face-windows-x64.zip -DestinationPath C:\two-face

# Run
C:\two-face\two-face.exe

Linux/macOS:

# Extract
tar xzf two-face-linux-x64.tar.gz

# Make executable
chmod +x two-face

# Run
./two-face

Building from Source

For the latest features or unsupported platforms, build from source.

Prerequisites

1. Rust Toolchain (1.70+)

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

2. Platform-Specific Dependencies

   Windows:

   • Visual Studio Build Tools
   • vcpkg with OpenSSL:

     git clone https://github.com/microsoft/vcpkg.git C:\vcpkg
     cd C:\vcpkg
     .\bootstrap-vcpkg.bat
     .\vcpkg install openssl:x64-windows
     $env:VCPKG_ROOT = "C:\vcpkg"
     

   Linux (Debian/Ubuntu):

   sudo apt install build-essential pkg-config libssl-dev libasound2-dev
   

   Linux (Fedora/RHEL):

   sudo dnf install gcc pkg-config openssl-devel alsa-lib-devel
   

   macOS:

   xcode-select --install
   # OpenSSL usually provided by system
   

Build Steps

# Clone repository
git clone https://github.com/nisugi/two-face.git
cd two-face

# Build release version
cargo build --release

# Binary is at target/release/two-face

Build Options

# Build without sound support (smaller binary)
cargo build --release --no-default-features

# Build with all features
cargo build --release --features sound

Data Directory

Two-Face stores configuration in a data directory:

Structure

~/.two-face/
├── config.toml          # Main configuration
├── layout.toml          # Window layout
├── keybinds.toml        # Key bindings
├── highlights.toml      # Text highlighting
├── colors.toml          # Color theme
├── simu.pem             # eAccess certificate (auto-downloaded)
├── two-face.log         # Debug log
└── profiles/            # Per-character profiles
    └── CharName/
        ├── layout.toml
        └── highlights.toml

Custom Data Directory

Override the default location:

# Via command line
two-face --data-dir /path/to/custom/dir

# Via environment variable
export TWO_FACE_DIR=/path/to/custom/dir
two-face

Verifying Installation

1. Check version:

   two-face --version
   

2. View help:

   two-face --help
   

3. Test terminal colors: Launch Two-Face and check if colors display correctly. If colors look wrong:

   # Set truecolor support
   export COLORTERM=truecolor
   two-face
   

Troubleshooting Installation

Windows: “vcruntime140.dll not found”

Install the Visual C++ Redistributable.

Windows: OpenSSL errors

Ensure VCPKG_ROOT is set and OpenSSL is installed via vcpkg.

Linux: “libasound.so not found”

Install ALSA library:

# Debian/Ubuntu
sudo apt install libasound2

# Fedora
sudo dnf install alsa-lib

macOS: “cannot be opened because the developer cannot be verified”

Right-click the binary, select “Open”, then click “Open” in the dialog.

All Platforms: Colors not working

1. Use a modern terminal (Windows Terminal, iTerm2, etc.)
2. Set COLORTERM=truecolor environment variable
3. Ensure your terminal supports 24-bit color

Next Steps

With Two-Face installed, continue to First Launch to connect to the game.

See Also

• Building from Source - Detailed build guide for developers
• Configuration Reference - Config file documentation
• Troubleshooting - Common issues and solutions

First Launch

This guide walks you through connecting to GemStone IV for the first time.

Choose Your Connection Mode

Two-Face supports two connection methods:

Option A: Lich Proxy Mode

Step 1: Start Lich

Launch Lich with your character. If you’re new to Lich, see the Lich documentation.

# Example Lich launch (varies by setup)
ruby lich.rb --login CharacterName

Lich will start listening on a port (default: 8000).

Step 2: Launch Two-Face

# Connect to Lich on default port
two-face

# Or specify a different port
two-face --port 8001

Step 3: Verify Connection

You should see:

1. Two-Face window appears
2. Game output starts flowing
3. Prompt (“>”) is visible

If the connection fails:

• Ensure Lich is running and logged in
• Check the port number matches
• See Connection Troubleshooting

Option B: Direct Mode

Direct mode connects without Lich, authenticating directly with Simutronics.

Step 1: Launch with Credentials

# Minimal command (will prompt for password)
two-face --direct --account YOUR_ACCOUNT --character CharName

# Specify game world
two-face --direct --account YOUR_ACCOUNT --character CharName --game prime

Game Worlds

Step 2: Enter Password

When prompted, enter your account password. The password is not echoed for security.

Password for account YOUR_ACCOUNT: ********

Step 3: Verify Connection

Two-Face will:

1. Authenticate with eAccess servers
2. Download/verify the server certificate (first time only)
3. Connect to the game server
4. Display game output

Initial Configuration

On first launch, Two-Face creates default configuration files:

~/.two-face/
├── config.toml      # Created with defaults
├── layout.toml      # Default window layout
├── keybinds.toml    # Default keybindings
├── highlights.toml  # Default highlights
└── colors.toml      # Default color theme

Character Profiles

To use per-character settings:

two-face --character CharName

This loads settings from ~/.two-face/profiles/CharName/ if they exist, falling back to defaults.

Essential First Steps

Once connected, try these:

1. Test Commands

Type a game command and press Enter:

look

2. Test Scrolling

Use Page Up/Down or scroll wheel to navigate history.

3. Open the Menu

Press Ctrl+M to open the main menu. Navigate with arrow keys.

4. Check Keybinds

Press Ctrl+? to view current keybindings.

First Launch Checklist

• Connected successfully
• Game output appears
• Commands work
• Colors display correctly
• Menu opens with Ctrl+M

Common First-Launch Issues

“Connection refused”

• Lich mode: Ensure Lich is running and logged in
• Direct mode: Check internet connection

No output appears

• Check that you’re connected to the right port
• Ensure Lich/game is actually sending data

Colors look wrong

• Set COLORTERM=truecolor in your terminal
• Use Windows Terminal (not CMD) on Windows

Password not accepted (Direct mode)

• Verify account name and password
• Try logging in via the official client first
• Delete ~/.two-face/simu.pem and retry

Next Steps

Now that you’re connected, take a Quick Tour to learn the essential controls.

See Also

• Quick Tour - Essential keyboard shortcuts
• Configuration - Customize your setup
• Connection Troubleshooting - Detailed connection help

Quick Tour

A 5-minute introduction to Two-Face’s essential controls and features.

The Interface

┌─────────────────────────────────────────────────────────────────────────┐
│ Two-Face v0.1.0                                                    [?]  │
├─────────────────────────────────────────────────────────────────────────┤
│ ┌─ Main ───────────────────────────┐ ┌─ Room ─────────────────────────┐ │
│ │                                  │ │ Town Square Central            │ │
│ │ A goblin attacks you!            │ │ This is the heart of the town. │ │
│ │ You swing your sword at goblin!  │ │ Obvious paths: n, e, s, w, out │ │
│ │ You hit for 45 damage!           │ │                                │ │
│ │ The goblin falls dead!           │ └────────────────────────────────┘ │
│ │                                  │ ┌─ Vitals ───┐ ┌─ Compass ──────┐ │
│ │ >                                │ │ HP ████████│ │     [N]        │ │
│ │                                  │ │ MP ██████░░│ │  [W] + [E]     │ │
│ │                                  │ │ ST ████████│ │     [S]        │ │
│ └──────────────────────────────────┘ └────────────┘ └────────────────┘ │
│ ┌─ Input ──────────────────────────────────────────────────────────────┐│
│ │ > attack goblin                                                      ││
│ └──────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────┘

Essential Keybinds

Navigation

Input

Menus & Popups

Client Control

Try It Now

1. Send a Command

Type look and press Enter. The room description appears in the main window.

2. Scroll History

Press Page Up to scroll back through game output. Press End to return to the bottom.

3. Use Command History

Press Up Arrow to recall your previous command. Press Down Arrow to go forward.

4. Open the Menu

Press Ctrl+M. Use arrow keys to navigate, Enter to select, Escape to close.

5. Focus a Window

Click on a window or use Ctrl+Tab to cycle focus. The focused window has a highlighted border.

Window Types

Two-Face displays several types of windows:

Text Windows

Scrollable text output (main game feed, thoughts, speech).

Controls:

• Scroll with Page Up/Down or mouse wheel
• Select text by clicking and dragging
• Copy selection with Ctrl+C

Progress Bars

Visual health, mana, stamina, etc.

Display:

HP ████████████████ 100%
MP ██████████░░░░░░  67%

Compass

Shows available exits with directional indicators.

Hands

Displays items in your left/right hands and prepared spell.

Indicators

Status icons for conditions (stunned, hidden, etc.).

The Main Menu

Press Ctrl+M to access:

┌─ Main Menu ────────────────────────┐
│ ► Window Editor                    │
│   Highlight Browser                │
│   Keybind Browser                  │
│   Color Browser                    │
│   ─────────────────────────        │
│   Reload Configuration             │
│   ─────────────────────────        │
│   Quit                             │
└────────────────────────────────────┘

Quick Customization

Change a Keybind

1. Press Ctrl+K to open the keybind browser
2. Navigate to the keybind you want to change
3. Press Enter to edit
4. Press the new key combination
5. Press Escape to close

Edit Highlights

1. Press Ctrl+H to open the highlight browser
2. Find an existing highlight or add a new one
3. Edit the pattern, colors, or conditions
4. Changes take effect immediately

Adjust a Window

1. Press Ctrl+E to open the window editor
2. Select a window from the list
3. Modify position, size, border, colors
4. Press Escape to close (changes auto-save)

Keyboard Reference Card

Print this for quick reference:

┌─────────────────────────────────────────────────────────────┐
│                  TWO-FACE QUICK REFERENCE                    │
├─────────────────────────────────────────────────────────────┤
│ NAVIGATION          │ MENUS              │ INPUT             │
│ PgUp/PgDn  Scroll   │ Ctrl+M  Main Menu  │ Enter   Send      │
│ Home/End   Top/Bot  │ Ctrl+H  Highlights │ Up/Down History   │
│ Ctrl+Tab   Windows  │ Ctrl+K  Keybinds   │ Ctrl+C  Copy      │
│ Tab        Tabs     │ Ctrl+E  Editor     │ Ctrl+V  Paste     │
│                     │ Escape  Close      │ Escape  Clear     │
├─────────────────────┴────────────────────┴───────────────────┤
│ F5 = Reload Config    Ctrl+L = Clear    Ctrl+Q = Quit       │
└─────────────────────────────────────────────────────────────┘

Next Steps

Now that you know the basics:

1. Customize Your Layout - Make it yours
2. Set Up Highlights - Color your world
3. Configure Keybinds - Optimize your workflow
4. Explore Widgets - Learn all widget types

See Also

• Keybind Actions Reference - Complete keybind list
• Configuration Guide - Config file details
• Tutorials - Step-by-step guides

Upgrading

How to update Two-Face to newer versions while preserving your configuration.

Before Upgrading

1. Backup Your Configuration

Your configuration files are precious. Back them up:

# Linux/macOS
cp -r ~/.two-face ~/.two-face.backup

# Windows (PowerShell)
Copy-Item -Recurse $env:USERPROFILE\.two-face $env:USERPROFILE\.two-face.backup

2. Check the Changelog

Review Version History for:

• Breaking changes
• New features
• Deprecated settings
• Migration requirements

Upgrade Methods

Pre-built Binaries

1. Download the new version from GitHub Releases
2. Replace the old binary with the new one
3. Launch Two-Face

Your configuration files in ~/.two-face/ are preserved automatically.

Building from Source

cd two-face

# Pull latest changes
git pull origin master

# Rebuild
cargo build --release

# New binary is at target/release/two-face

Configuration Compatibility

Automatic Migration

Two-Face attempts to handle configuration changes automatically:

• Missing keys use default values
• Deprecated keys are ignored with warnings
• New features are disabled until configured

Manual Migration

For breaking changes, you may need to update config files manually. Check the version-specific notes below.

Version-Specific Upgrade Notes

v0.1.x → v0.2.x

No breaking changes expected during alpha.

Future Versions

Check Version History for detailed migration guides when released.

Troubleshooting Upgrades

Config file errors after upgrade

1. Check the error message for the problematic key
2. Compare your config with the default files
3. Update or remove the problematic setting

Reset to defaults

If needed, reset configuration:

# Backup first!
cp -r ~/.two-face ~/.two-face.backup

# Remove old config (keeps profiles)
rm ~/.two-face/*.toml

# Launch Two-Face to regenerate defaults
two-face

Partial reset

Reset specific files:

# Reset just keybinds
rm ~/.two-face/keybinds.toml
two-face  # Regenerates default keybinds

Downgrading

To revert to an older version:

1. Download the older release
2. Replace the binary
3. Restore your backed-up configuration if needed

Note: Config files from newer versions may not work with older versions. Use your backup.

See Also

• Version History - Changelog and migration guides
• Default Files - Default configuration reference
• Troubleshooting - General troubleshooting

Configuration

Two-Face uses TOML files for all configuration. This section provides complete documentation for each configuration file.

Configuration Files

Two-Face loads configuration from these files in your data directory (~/.two-face/):

Hot Reload: Press F5 to reload all configuration without restarting.

File Locations

Default Location

Custom Location

Override with --data-dir or TWO_FACE_DIR:

# Command line
two-face --data-dir /custom/path

# Environment variable
export TWO_FACE_DIR=/custom/path

Character Profiles

Per-character configuration lives in ~/.two-face/profiles/<CharName>/:

~/.two-face/
├── config.toml           # Global defaults
├── layout.toml
├── keybinds.toml
├── highlights.toml
├── colors.toml
└── profiles/
    ├── Warrior/          # Character-specific overrides
    │   ├── layout.toml
    │   └── highlights.toml
    └── Wizard/
        ├── layout.toml
        └── highlights.toml

Loading Order

1. Load global defaults from ~/.two-face/
2. If --character specified, overlay from profiles/<CharName>/
3. Character files only need to contain overrides, not complete configs

Usage

# Load Warrior's profile
two-face --character Warrior

Configuration Syntax

All config files use TOML syntax:

# Comments start with #

# Simple key-value
setting = "value"
number = 42
enabled = true

# Nested tables
[section]
key = "value"

# Inline tables
point = { x = 10, y = 20 }

# Arrays
list = ["one", "two", "three"]

# Array of tables
[[items]]
name = "first"

[[items]]
name = "second"

Color Values

Colors can be specified as:

# Hex RGB
color = "#FF5500"

# Hex RRGGBB (same as above)
color = "#ff5500"

# Named color (from palette)
color = "bright_red"

# Preset reference
color = "@speech"  # Uses the 'speech' preset color

Size Values

# Fixed pixels
width = 40

# Percentage of parent
width = "50%"

Default Files

Two-Face ships with sensible defaults embedded in the binary. On first run, these are written to your data directory if the files don’t exist.

See Default Files Reference for complete default content.

Validation

Two-Face validates configuration on load:

• Errors: Invalid syntax or required fields prevent loading
• Warnings: Unknown keys or deprecated settings log warnings but allow loading
• Missing files: Created from defaults

Check ~/.two-face/two-face.log for configuration warnings.

Quick Reference

Most Common Settings

Reload Configuration

• F5: Reload all config files
• Ctrl+M → Reload: Same via menu
• Restart: Always picks up changes

File Reference

See Also

• Creating Layouts - Layout design guide
• Creating Themes - Theme authoring
• Default Files - Built-in defaults

config.toml Reference

The main configuration file controlling Two-Face’s behavior, connection settings, and general preferences.

Location

~/.two-face/config.toml

Complete Reference

#
# Two-Face Configuration
#

[connection]
# Default host for Lich proxy mode
host = "127.0.0.1"

# Default port for Lich proxy mode
port = 8000

# Default character name (used for profile loading)
character = ""

# Timeout for connection attempts (seconds)
timeout = 30

[interface]
# Enable clickable links in game text
links = true

# Show window borders by default
show_borders = true

# Default border style: "plain", "rounded", "double", "thick"
border_style = "rounded"

# Mouse support
mouse = true

# Scroll speed (lines per scroll event)
scroll_speed = 3

# Command history size
history_size = 1000

[sound]
# Enable sound effects
enabled = true

# Master volume (0.0 - 1.0)
volume = 0.8

# Play startup music
startup_music = true

# Sound file paths (relative to data dir or absolute)
# alert_sound = "sounds/alert.wav"

[tts]
# Enable text-to-speech
enabled = false

# TTS rate (words per minute, platform dependent)
rate = 150

# Which streams to speak
streams = ["main"]

# Speak room descriptions
speak_rooms = true

# Speak player speech
speak_speech = true

[logging]
# Log level: "error", "warn", "info", "debug", "trace"
level = "warn"

# Log file path (relative to data dir)
file = "two-face.log"

# Log to console (for debugging)
console = false

[behavior]
# Auto-scroll to bottom on new text
auto_scroll = true

# Flash window on important events
flash_on_alert = false

# Notification sound on important events
sound_on_alert = false

# Pause input during roundtime (experimental)
pause_on_rt = false

[performance]
# Maximum lines to buffer per text window
max_buffer_lines = 2000

# Frame rate target
target_fps = 60

# Enable performance metrics collection
collect_metrics = true

Section Details

[connection]

Controls how Two-Face connects to the game.

Note: Direct mode (--direct) ignores these settings and uses command-line credentials.

[interface]

Visual and interaction settings.

Border styles:

• "plain" - Single line: ─│─│┌┐└┘
• "rounded" - Rounded corners: ─│─│╭╮╰╯
• "double" - Double line: ═║═║╔╗╚╝
• "thick" - Thick line: ━┃━┃┏┓┗┛

[sound]

Audio settings.

Note: Requires the sound feature to be compiled in.

[tts]

Text-to-speech accessibility features.

Supported streams: "main", "speech", "thoughts", "combat"

[logging]

Diagnostic logging configuration.

Log levels (from least to most verbose):

• "error" - Only errors
• "warn" - Errors and warnings
• "info" - Normal operation info
• "debug" - Debugging details
• "trace" - Very verbose tracing

[behavior]

Client behavior tweaks.

[performance]

Performance tuning.

Examples

Minimal Config

[connection]
port = 8000
character = "MyCharacter"

High-Performance Config

[performance]
max_buffer_lines = 1000
target_fps = 120
collect_metrics = false

[interface]
links = false  # Disable link parsing for speed

Accessibility Config

[tts]
enabled = true
rate = 175
streams = ["main", "speech"]
speak_rooms = true
speak_speech = true

[interface]
scroll_speed = 5

Environment Variable Overrides

Some settings can be overridden via environment variables:

See Also

• layout.toml - Window layout configuration
• Character Profiles - Per-character settings
• Environment Variables - All environment variables

layout.toml Reference

The layout configuration file defines all windows, their positions, sizes, and visual properties.

Location

~/.two-face/layout.toml

Structure Overview

# Global layout settings
[layout]
columns = 120
rows = 40

# Window definitions
[[windows]]
name = "main"
type = "text"
# ... window properties

[[windows]]
name = "room"
type = "room"
# ... window properties

[layout] Section

Global layout dimensions and defaults.

[layout]
# Terminal grid size
columns = 120        # Total columns
rows = 40            # Total rows

# Default window settings
default_border = true
default_border_style = "rounded"

[[windows]] Array

Each [[windows]] entry defines a single window.

Common Properties

These properties apply to all window types:

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

# Position (choose one method)
row = 0                    # Row position
col = 0                    # Column position
# OR
x = 0                      # Pixel X position
y = 0                      # Pixel Y position

# Size
width = 80                 # Width in columns
height = 30                # Height in rows
# OR percentage
width = "60%"              # Percentage of parent width
height = "80%"             # Percentage of parent height

# Visual
show_border = true         # Show window border
border_style = "rounded"   # Border style
border_sides = "all"       # Which sides have borders
show_title = true          # Show title bar
title = "Main Window"      # Custom title (default: name)
transparent_background = false  # Transparent background

# Colors (override theme)
border_color = "#5588AA"   # Border color
background_color = "#000000"  # Background color
text_color = "#CCCCCC"     # Text color

Position Properties

Note: Use row/col for grid-based layouts, x/y for pixel-precise positioning.

Size Properties

Percentage sizing:

width = "50%"    # 50% of layout width
height = "100%"  # Full layout height

Border Properties

Border sides:

• "all" - All four sides
• "none" - No borders
• "top" - Top only
• "bottom" - Bottom only
• "left" - Left only
• "right" - Right only
• "top,bottom" - Specific sides (comma-separated)
• "horizontal" - Top and bottom
• "vertical" - Left and right

Window Types

Text Window

Scrollable text display for game output.

[[windows]]
name = "main"
type = "text"
row = 0
col = 0
width = 80
height = 30

# Text-specific options
stream = "main"           # Game stream to display
buffer_size = 2000        # Maximum lines to buffer
word_wrap = true          # Enable word wrapping

Common streams: main, speech, thoughts, combat, death, logons, familiar, group

Tabbed Text Window

Multiple streams in tabbed interface.

[[windows]]
name = "channels"
type = "tabbed_text"
row = 0
col = 80
width = 40
height = 30

# Tab configuration
tabs = ["speech", "thoughts", "combat"]
default_tab = "speech"
show_tab_bar = true

Command Input

Text input field for commands.

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

# Input-specific options
prompt = "> "
history = true

Progress Bar

Displays a value as a filled bar.

[[windows]]
name = "health"
type = "progress"
row = 0
col = 80
width = 20
height = 1

# Progress-specific options
stat = "health"           # Stat to track
show_value = true         # Show "425/500"
show_percentage = false   # Show "85%"
bar_color = "#00FF00"     # Bar fill color

Stat IDs: health, mana, spirit, stamina, encumbrance

Countdown

Countdown timer display.

[[windows]]
name = "roundtime"
type = "countdown"
row = 2
col = 80
width = 20
height = 1

# Countdown-specific options
countdown_type = "roundtime"  # "roundtime" or "casttime"
show_seconds = true
icon = "⏱"

Compass

Directional compass display.

[[windows]]
name = "compass"
type = "compass"
row = 5
col = 100
width = 10
height = 5

# Compass-specific options
style = "graphical"       # "graphical" or "text"
show_labels = true        # Show N/S/E/W labels

Hand

Left/right hand or spell display.

[[windows]]
name = "right_hand"
type = "hand"
row = 10
col = 100
width = 15
height = 1

# Hand-specific options
hand_type = "right"       # "left", "right", or "spell"
icon = "🤚"

Indicator

Status indicator widget.

[[windows]]
name = "status"
type = "indicator"
row = 12
col = 100
width = 20
height = 1

# Indicator-specific options
indicators = ["stunned", "hidden", "poisoned"]
style = "icons"           # "icons" or "text"

Indicator IDs: stunned, hidden, webbed, poisoned, diseased, bleeding, prone, kneeling, sitting

Room Window

Room description display.

[[windows]]
name = "room"
type = "room"
row = 0
col = 80
width = 40
height = 10

# Room-specific options
show_title = true         # Show room name
show_description = true   # Show room desc
show_exits = true         # Show obvious exits
show_objects = true       # Show items/creatures
show_players = true       # Show other players

Injury Doll

Body injury display.

[[windows]]
name = "injuries"
type = "injury_doll"
row = 15
col = 100
width = 15
height = 10

# Injury-specific options
show_labels = true
compact = false

Performance Monitor

Performance metrics display.

[[windows]]
name = "performance"
type = "performance"
row = 0
col = 0
width = 30
height = 15

# Which metrics to show
show_fps = true
show_frame_times = true
show_render_times = true
show_net = true
show_parse = true
show_memory = true
show_lines = true
show_uptime = true

Layout Examples

Basic Two-Column Layout

[layout]
columns = 120
rows = 40

[[windows]]
name = "main"
type = "text"
row = 0
col = 0
width = 80
height = 38

[[windows]]
name = "room"
type = "room"
row = 0
col = 80
width = 40
height = 15

[[windows]]
name = "vitals"
type = "progress"
stat = "health"
row = 15
col = 80
width = 40
height = 1

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

Hunting Layout

See Hunting Setup Tutorial for a complete example.

Minimal Layout

[layout]
columns = 80
rows = 24

[[windows]]
name = "main"
type = "text"
row = 0
col = 0
width = 80
height = 22
show_border = false

[[windows]]
name = "input"
type = "command_input"
row = 22
col = 0
width = 80
height = 2
show_border = false

See Also

• Creating Layouts - Layout design guide
• Widget Reference - Detailed widget documentation
• Tutorials - Complete layout examples

keybinds.toml Reference

The keybinds configuration file maps keyboard shortcuts to actions.

Location

~/.two-face/keybinds.toml

Structure Overview

[[keybinds]]
key = "Enter"
action = "send"

[[keybinds]]
key = "Ctrl+Q"
action = "quit"

[[keybinds]]
key = "F1"
action = "send"
argument = "look"

Keybind Properties

Each [[keybinds]] entry defines one key mapping:

[[keybinds]]
# Required
key = "Ctrl+S"            # Key combination
action = "send"           # Action to perform

# Optional
argument = "save"         # Action argument
description = "Save game" # Description for help
context = "input"         # When this binding is active

Key Syntax

Basic Keys

key = "A"         # Letter A
key = "1"         # Number 1
key = "F1"        # Function key
key = "Enter"     # Enter key
key = "Space"     # Space bar
key = "Tab"       # Tab key
key = "Escape"    # Escape key

Modifier Keys

Combine modifiers with +:

key = "Ctrl+S"          # Ctrl + S
key = "Alt+F4"          # Alt + F4
key = "Shift+Tab"       # Shift + Tab
key = "Ctrl+Shift+Z"    # Ctrl + Shift + Z
key = "Ctrl+Alt+Delete" # Multiple modifiers

Available modifiers:

• Ctrl - Control key
• Alt - Alt key
• Shift - Shift key

Special Keys

Numpad Keys

key = "Numpad0"   # Numpad 0
key = "Numpad+"   # Numpad plus
key = "Numpad*"   # Numpad multiply
key = "NumpadEnter"  # Numpad enter

Actions

Input Actions

Examples:

[[keybinds]]
key = "Enter"
action = "send"

[[keybinds]]
key = "F1"
action = "send"
argument = "attack"

[[keybinds]]
key = "Ctrl+K"
action = "clear_input"

Navigation Actions

Examples:

[[keybinds]]
key = "PageUp"
action = "scroll_page_up"

[[keybinds]]
key = "Ctrl+Tab"
action = "focus_next"

[[keybinds]]
key = "Ctrl+1"
action = "focus_window"
argument = "main"

Menu Actions

Examples:

[[keybinds]]
key = "Ctrl+M"
action = "open_menu"

[[keybinds]]
key = "Ctrl+H"
action = "open_highlight_browser"

[[keybinds]]
key = "Escape"
action = "close_popup"

Client Actions

Examples:

[[keybinds]]
key = "Ctrl+Q"
action = "quit"

[[keybinds]]
key = "F5"
action = "reload_config"

[[keybinds]]
key = "Ctrl+L"
action = "clear_window"
argument = "main"

Game Actions

Examples:

[[keybinds]]
key = "Numpad8"
action = "move"
argument = "north"

[[keybinds]]
key = "Numpad2"
action = "move"
argument = "south"

Contexts

Keybinds can be limited to specific contexts:

Examples:

# Only active when input is focused
[[keybinds]]
key = "Tab"
action = "autocomplete"
context = "input"

# Only active in menus
[[keybinds]]
key = "Enter"
action = "select"
context = "menu"

Default Keybinds

Two-Face ships with these defaults:

Navigation

[[keybinds]]
key = "PageUp"
action = "scroll_page_up"

[[keybinds]]
key = "PageDown"
action = "scroll_page_down"

[[keybinds]]
key = "Home"
action = "scroll_top"

[[keybinds]]
key = "End"
action = "scroll_bottom"

[[keybinds]]
key = "Ctrl+Tab"
action = "focus_next"

Input

[[keybinds]]
key = "Enter"
action = "send"

[[keybinds]]
key = "Up"
action = "history_prev"

[[keybinds]]
key = "Down"
action = "history_next"

[[keybinds]]
key = "Ctrl+C"
action = "copy"

[[keybinds]]
key = "Ctrl+V"
action = "paste"

Menus

[[keybinds]]
key = "Ctrl+M"
action = "open_menu"

[[keybinds]]
key = "Ctrl+H"
action = "open_highlight_browser"

[[keybinds]]
key = "Ctrl+K"
action = "open_keybind_browser"

[[keybinds]]
key = "Ctrl+E"
action = "open_window_editor"

[[keybinds]]
key = "Escape"
action = "close_popup"

Client

[[keybinds]]
key = "Ctrl+Q"
action = "quit"

[[keybinds]]
key = "F5"
action = "reload_config"

[[keybinds]]
key = "Ctrl+L"
action = "clear_window"
argument = "main"

Example Configurations

Numpad Movement

[[keybinds]]
key = "Numpad8"
action = "send"
argument = "north"
description = "Move north"

[[keybinds]]
key = "Numpad2"
action = "send"
argument = "south"

[[keybinds]]
key = "Numpad4"
action = "send"
argument = "west"

[[keybinds]]
key = "Numpad6"
action = "send"
argument = "east"

[[keybinds]]
key = "Numpad7"
action = "send"
argument = "northwest"

[[keybinds]]
key = "Numpad9"
action = "send"
argument = "northeast"

[[keybinds]]
key = "Numpad1"
action = "send"
argument = "southwest"

[[keybinds]]
key = "Numpad3"
action = "send"
argument = "southeast"

[[keybinds]]
key = "Numpad5"
action = "send"
argument = "out"

Combat Macros

[[keybinds]]
key = "F1"
action = "send"
argument = "attack"
description = "Basic attack"

[[keybinds]]
key = "F2"
action = "send"
argument = "incant 101"
description = "Cast Spirit Warding I"

[[keybinds]]
key = "F3"
action = "send"
argument = "stance defensive"
description = "Defensive stance"

See Also

• Keybind Actions Reference - Complete action list
• Quick Tour - Default keybinds
• Customization - Keybind customization guide

highlights.toml Reference

The highlights configuration file defines text patterns and their visual styling.

Location

~/.two-face/highlights.toml

Structure Overview

[[highlights]]
name = "creatures"
pattern = "(goblin|orc|troll)"
fg = "#FF0000"
bold = true

[[highlights]]
name = "player_speech"
pattern = '^\w+ (says|asks|exclaims),'
fg = "#00FF00"
stream = "main"

Highlight Properties

Each [[highlights]] entry defines one highlighting rule:

[[highlights]]
# Identity
name = "my_highlight"       # Unique name (required)
pattern = "text to match"   # Regex pattern (required)

# Colors
fg = "#FF0000"              # Foreground color
bg = "#000000"              # Background color

# Styling
bold = false                # Bold text
italic = false              # Italic text
underline = false           # Underlined text

# Scope
stream = "main"             # Limit to stream (optional)
span_type = "Normal"        # Only match span type (optional)

# Performance
fast_parse = false          # Use literal matching
enabled = true              # Enable/disable
priority = 0                # Match priority (higher = first)

Required Properties

Color Properties

Color formats:

fg = "#FF5500"        # Hex RGB
fg = "bright_red"     # Palette name
fg = "@speech"        # Preset reference

Style Properties

Scope Properties

Stream values: main, speech, thoughts, combat, etc.

Span types:

• Normal - Regular text
• Link - Clickable links
• Monsterbold - Creature names
• Speech - Player dialogue
• Spell - Spell names

Performance Properties

Pattern Syntax

Highlights use Rust regex syntax. Key features:

Basic Patterns

# Literal text
pattern = "goblin"

# Case insensitive
pattern = "(?i)goblin"

# Word boundaries
pattern = "\\bgoblin\\b"

# Multiple words
pattern = "goblin|orc|troll"

Character Classes

# Any digit
pattern = "\\d+"

# Any word character
pattern = "\\w+"

# Any whitespace
pattern = "\\s+"

# Custom class
pattern = "[A-Z][a-z]+"

Anchors

# Start of line
pattern = "^You attack"

# End of line
pattern = "falls dead!$"

# Word boundary
pattern = "\\bgoblin\\b"

Groups and Captures

# Non-capturing group
pattern = "(?:goblin|orc)"

# Capturing group (for future use)
pattern = "(\\w+) says,"

Escaping Special Characters

These characters must be escaped with \\:

. * + ? ^ $ { } [ ] ( ) | \

# Match literal period
pattern = "Mr\\. Smith"

# Match literal asterisk
pattern = "\\*\\*emphasis\\*\\*"

Fast Parse Mode

For simple literal patterns, fast_parse = true uses Aho-Corasick algorithm:

[[highlights]]
name = "names"
pattern = "Bob|Alice|Charlie"
fg = "#FFFF00"
fast_parse = true

When to use fast_parse:

• Pattern is literal strings (no regex)
• Pattern has many alternatives (names, items)
• High-frequency matching needed

When NOT to use fast_parse:

• Pattern uses regex features
• Pattern needs word boundaries
• Pattern uses anchors (^, $)

Priority System

When multiple highlights match, priority determines which wins:

# Higher priority wins
[[highlights]]
name = "important"
pattern = "critical"
fg = "#FF0000"
priority = 100

# Lower priority, same match
[[highlights]]
name = "general"
pattern = ".*"
fg = "#808080"
priority = 0

Default priorities:

• Monsterbold spans: Highest
• Link spans: High
• User highlights: Medium (configurable)
• Preset colors: Low

Stream Filtering

Limit highlights to specific streams:

# Only in main window
[[highlights]]
name = "combat"
pattern = "You (hit|miss)"
fg = "#FF0000"
stream = "main"

# Only in thoughts
[[highlights]]
name = "esp"
pattern = "\\[ESP\\]"
fg = "#00FFFF"
stream = "thoughts"

Common Patterns

Creature Names

[[highlights]]
name = "creatures"
pattern = "(?i)\\b(goblin|orc|troll|kobold|giant)s?\\b"
fg = "#FF6600"
bold = true

Player Speech

[[highlights]]
name = "speech"
pattern = '^(\\w+) (says|asks|exclaims|whispers),'
fg = "#00FF00"

Your Character Name

[[highlights]]
name = "my_name"
pattern = "\\bYourCharacterName\\b"
fg = "#FFFF00"
bold = true

Damage Numbers

[[highlights]]
name = "damage"
pattern = "\\b\\d+\\s+points?\\s+of\\s+damage"
fg = "#FF0000"
bold = true

Silver/Gold

[[highlights]]
name = "silver"
pattern = "\\d+\\s+silver"
fg = "#C0C0C0"
bold = true

[[highlights]]
name = "gold"
pattern = "\\d+\\s+gold"
fg = "#FFD700"
bold = true

Room Exits

[[highlights]]
name = "exits"
pattern = "Obvious (paths|exits):"
fg = "#00FFFF"

ESP/Thoughts

[[highlights]]
name = "esp"
pattern = "^\\[.*?\\]"
fg = "#FF00FF"
stream = "thoughts"

Complete Example

# Two-Face Highlights Configuration

# Creature highlighting
[[highlights]]
name = "creatures"
pattern = "(?i)\\b(goblin|orc|troll|kobold|giant rat|wolf|bear)s?\\b"
fg = "#FF6600"
bold = true
priority = 50

# Player names (customize this list)
[[highlights]]
name = "friends"
pattern = "\\b(Alice|Bob|Charlie)\\b"
fg = "#00FF00"
fast_parse = true
priority = 60

# Damage taken
[[highlights]]
name = "damage_taken"
pattern = "strikes you|hits you|bites you"
fg = "#FF0000"
bold = true
priority = 70

# Damage dealt
[[highlights]]
name = "damage_dealt"
pattern = "You (hit|strike|slash)"
fg = "#00FF00"
priority = 70

# Currency
[[highlights]]
name = "silver"
pattern = "\\d+\\s+silvers?"
fg = "#C0C0C0"

[[highlights]]
name = "gold"
pattern = "\\b(gold|golden)\\b"
fg = "#FFD700"

# Important messages
[[highlights]]
name = "roundtime"
pattern = "Roundtime:"
fg = "#FF00FF"
bold = true

[[highlights]]
name = "death"
pattern = "You have died|DEAD"
fg = "#FF0000"
bg = "#400000"
bold = true
priority = 100

See Also

• Highlight Patterns Guide - Advanced patterns
• Colors Reference - Color values and palettes
• Performance - Highlight optimization

colors.toml Reference

The colors configuration file defines the visual theme including presets, palettes, and UI colors.

Location

~/.two-face/colors.toml

Structure Overview

# Named presets (game text styling)
[presets]
speech = { fg = "#53a684" }
monsterbold = { fg = "#a29900" }

# Color palette (named colors)
[palette]
bright_red = "#FF5555"
bright_green = "#55FF55"

# UI element colors
[ui]
border = "#5588AA"
background = "#000000"

# Prompt colors
[prompt]
default = "#808080"

[presets] Section

Presets define colors for game text elements:

[presets]
# Speech/dialogue
speech = { fg = "#53a684" }

# Creature names (monsterbold)
monsterbold = { fg = "#a29900" }

# Clickable links
links = { fg = "#477ab3" }

# Command echoes
commands = { fg = "#477ab3" }

# Whispers
whisper = { fg = "#4682B4" }

# Room name
roomName = { fg = "#9BA2B2", bg = "#395573" }

# Room description
roomDesc = { fg = "#CCCCCC" }

# Thoughts/ESP
thought = { fg = "#FF00FF" }

# Combat messages
combat = { fg = "#FF6600" }

Preset Format

Each preset can have:

[presets]
name = { fg = "#RRGGBB", bg = "#RRGGBB", bold = true }

Standard Presets

These presets are used by the game protocol:

[palette] Section

Named colors for use elsewhere in configuration:

[palette]
# Base colors
black = "#000000"
white = "#FFFFFF"
red = "#AA0000"
green = "#00AA00"
blue = "#0000AA"
yellow = "#AAAA00"
cyan = "#00AAAA"
magenta = "#AA00AA"

# Bright variants
bright_black = "#555555"
bright_white = "#FFFFFF"
bright_red = "#FF5555"
bright_green = "#55FF55"
bright_blue = "#5555FF"
bright_yellow = "#FFFF55"
bright_cyan = "#55FFFF"
bright_magenta = "#FF55FF"

# Custom colors
health_high = "#00FF00"
health_mid = "#FFFF00"
health_low = "#FF0000"
mana_color = "#0088FF"

Using Palette Colors

Reference palette colors in other config files:

# In highlights.toml
[[highlights]]
name = "damage"
pattern = "damage"
fg = "bright_red"  # Uses palette.bright_red

# In layout.toml
[[windows]]
name = "health"
type = "progress"
bar_color = "health_high"  # Uses palette.health_high

[ui] Section

Colors for UI elements:

[ui]
# Borders
border = "#5588AA"
border_focused = "#88AACC"

# Backgrounds
background = "#000000"
window_background = "#0A0A0A"

# Text
text = "#CCCCCC"
text_dim = "#808080"
text_highlight = "#FFFFFF"

# Selection
selection_bg = "#264F78"
selection_fg = "#FFFFFF"

# Scrollbar
scrollbar_track = "#1A1A1A"
scrollbar_thumb = "#404040"

# Menu
menu_bg = "#1A1A1A"
menu_fg = "#CCCCCC"
menu_selected_bg = "#264F78"
menu_selected_fg = "#FFFFFF"

# Input
input_bg = "#0A0A0A"
input_fg = "#FFFFFF"
input_cursor = "#FFFFFF"

UI Color Reference

[prompt] Section

Colors for the game prompt:

[prompt]
# Default prompt color
default = "#808080"

# Combat/RT prompt
combat = "#FF0000"

# Safe prompt
safe = "#00FF00"

[spell] Section

Colors for spell circle indicators:

[spell]
# Major Elemental
major_elemental = "#FF6600"

# Minor Elemental
minor_elemental = "#FFAA00"

# Major Spiritual
major_spiritual = "#00AAFF"

# Minor Spiritual
minor_spiritual = "#0066FF"

# Bard
bard = "#FF00FF"

# Wizard
wizard = "#AA00FF"

# Sorcerer
sorcerer = "#660066"

# Ranger
ranger = "#00AA00"

# Paladin
paladin = "#FFFF00"

# Cleric
cleric = "#FFFFFF"

# Empath
empath = "#00FFAA"

Color Formats

Hex RGB

color = "#FF5500"    # 6-digit hex
color = "#F50"       # 3-digit hex (expanded to #FF5500)

Named Colors

Reference palette entries:

color = "bright_red"     # From [palette]
color = "health_high"    # Custom palette entry

Preset References

Reference preset colors with @:

color = "@speech"        # Uses presets.speech.fg
color = "@monsterbold"   # Uses presets.monsterbold.fg

Complete Theme Example

# Two-Face Dark Theme

[presets]
speech = { fg = "#53a684" }
monsterbold = { fg = "#e8b923", bold = true }
links = { fg = "#477ab3" }
commands = { fg = "#477ab3" }
whisper = { fg = "#4682B4" }
roomName = { fg = "#9BA2B2", bg = "#395573" }
roomDesc = { fg = "#B0B0B0" }
thought = { fg = "#DA70D6" }

[palette]
# Base colors
black = "#000000"
white = "#FFFFFF"
red = "#CC0000"
green = "#00CC00"
blue = "#0066CC"
yellow = "#CCCC00"
cyan = "#00CCCC"
magenta = "#CC00CC"

# Bright variants
bright_red = "#FF5555"
bright_green = "#55FF55"
bright_blue = "#5588FF"
bright_yellow = "#FFFF55"
bright_cyan = "#55FFFF"
bright_magenta = "#FF55FF"

# Custom
health = "#00FF00"
mana = "#0088FF"
spirit = "#00FFFF"
stamina = "#FFFF00"

[ui]
border = "#3A5F7A"
border_focused = "#5588AA"
background = "#0A0A0A"
window_background = "#0F0F0F"
text = "#CCCCCC"
text_dim = "#666666"
text_highlight = "#FFFFFF"
selection_bg = "#264F78"
selection_fg = "#FFFFFF"
menu_bg = "#1A1A1A"
menu_fg = "#CCCCCC"
menu_selected_bg = "#264F78"
menu_selected_fg = "#FFFFFF"

[prompt]
default = "#666666"
combat = "#FF4444"
safe = "#44FF44"

Theme Switching

Two-Face supports hot theme switching:

1. Edit colors.toml
2. Press F5 to reload
3. New colors apply immediately

Or create multiple theme files and switch by copying:

cp themes/solarized.toml ~/.two-face/colors.toml
# Then press F5 in Two-Face

See Also

• Creating Themes - Theme authoring guide
• Preset Colors Reference - All preset names
• Color Codes - Hex color reference

Character Profiles

Two-Face supports per-character configuration through profiles, allowing different layouts, highlights, and settings for each character.

Overview

Profiles let you:

• Use different layouts for different playstyles (hunting warrior vs. merchant)
• Customize highlights per character (different friend lists, creature lists)
• Override any global setting on a per-character basis

Profile Structure

Profiles are stored in ~/.two-face/profiles/<CharacterName>/:

~/.two-face/
├── config.toml           # Global defaults
├── layout.toml           # Global layout
├── keybinds.toml         # Global keybinds
├── highlights.toml       # Global highlights
├── colors.toml           # Global colors
│
└── profiles/
    ├── Warrior/          # Warrior's profile
    │   ├── layout.toml   # Warrior's layout
    │   └── highlights.toml
    │
    ├── Wizard/           # Wizard's profile
    │   ├── layout.toml
    │   ├── highlights.toml
    │   └── keybinds.toml
    │
    └── Merchant/         # Merchant's profile
        └── layout.toml

Using Profiles

Loading a Profile

Specify the character name when launching:

two-face --character Warrior

Or set a default in config.toml:

[connection]
character = "Warrior"

Profile Loading Order

1. Load global config from ~/.two-face/
2. If profile exists, overlay files from profiles/<CharName>/
3. Missing profile files fall back to global

Example flow for --character Warrior:

Creating a Profile

Method 1: Manual Creation

# Create profile directory
mkdir -p ~/.two-face/profiles/MyCharacter

# Copy files you want to customize
cp ~/.two-face/layout.toml ~/.two-face/profiles/MyCharacter/
cp ~/.two-face/highlights.toml ~/.two-face/profiles/MyCharacter/

# Edit the copies
vim ~/.two-face/profiles/MyCharacter/layout.toml

Method 2: Start from Defaults

Launch with a new character name:

two-face --character NewCharacter

Two-Face uses global defaults. Then copy and customize as needed.

Profile-Specific Settings

Layout Differences

A warrior might want:

# profiles/Warrior/layout.toml

[[windows]]
name = "main"
type = "text"
width = "70%"
height = "80%"

# Large status area for combat
[[windows]]
name = "vitals"
type = "dashboard"
width = "30%"
height = "40%"

A merchant might prefer:

# profiles/Merchant/layout.toml

[[windows]]
name = "main"
type = "text"
width = "100%"
height = "90%"

# No combat widgets, maximize text area

Highlight Differences

Warrior with creature highlights:

# profiles/Warrior/highlights.toml

[[highlights]]
name = "hunting_targets"
pattern = "(?i)\\b(goblin|orc|troll|giant)s?\\b"
fg = "#FF6600"
bold = true

Merchant with item highlights:

# profiles/Merchant/highlights.toml

[[highlights]]
name = "valuable_items"
pattern = "(?i)\\b(gold|silver|gem|diamond)s?\\b"
fg = "#FFD700"
bold = true

[[highlights]]
name = "materials"
pattern = "(?i)\\b(leather|silk|velvet|mithril)\\b"
fg = "#00FFFF"

Keybind Differences

Combat character:

# profiles/Warrior/keybinds.toml

[[keybinds]]
key = "F1"
action = "send"
argument = "attack"

[[keybinds]]
key = "F2"
action = "send"
argument = "feint"

Spellcaster:

# profiles/Wizard/keybinds.toml

[[keybinds]]
key = "F1"
action = "send"
argument = "incant 901"

[[keybinds]]
key = "F2"
action = "send"
argument = "incant 903"

Shared vs. Profile-Specific

Keep Global (Shared)

• colors.toml - Usually same theme everywhere
• config.toml - Connection settings shared

Make Profile-Specific

• layout.toml - Different layouts per playstyle
• highlights.toml - Different creatures/items/friends
• keybinds.toml - Different combat macros

Profile Tips

1. Start Simple

Only create profile overrides for files you need to change. Let others fall back to global.

2. Use Consistent Names

Match your character name exactly (case-sensitive on some systems):

# Good
--character Nisugi
~/.two-face/profiles/Nisugi/

# May not work
--character nisugi
~/.two-face/profiles/Nisugi/  # Case mismatch!

3. Share Common Elements

For settings shared across some (but not all) characters, create a “base” profile and copy from it:

# Create a hunting base
cp -r ~/.two-face/profiles/Warrior ~/.two-face/profiles/hunting-base

# New hunting character
cp -r ~/.two-face/profiles/hunting-base ~/.two-face/profiles/NewHunter

4. Version Control

Consider version controlling your profiles:

cd ~/.two-face
git init
git add .
git commit -m "Initial Two-Face configuration"

Troubleshooting Profiles

Profile Not Loading

1. Check character name spelling (case-sensitive)
2. Verify directory exists: ls ~/.two-face/profiles/
3. Check file permissions
4. Look for errors in ~/.two-face/two-face.log

Wrong Settings Applied

1. Check which profile is loaded (shown on startup)
2. Verify the file exists in the profile directory
3. Check for syntax errors in the profile file

Resetting a Profile

# Remove profile to use global defaults
rm -rf ~/.two-face/profiles/CharName/

# Or reset specific file
rm ~/.two-face/profiles/CharName/layout.toml

Example: Multi-Character Setup

~/.two-face/
├── config.toml
├── layout.toml           # Balanced default layout
├── keybinds.toml         # Common keybinds
├── highlights.toml       # Common highlights
├── colors.toml           # Dark theme for all
│
└── profiles/
    ├── Ranger/
    │   ├── layout.toml   # Compact hunting layout
    │   ├── highlights.toml # Creature + foraging
    │   └── keybinds.toml # Ranged combat macros
    │
    ├── Empath/
    │   ├── layout.toml   # Group-focused layout
    │   └── highlights.toml # Wounds + group members
    │
    └── Bard/
        ├── layout.toml   # RP-friendly layout
        └── highlights.toml # Song + speech focus

See Also

• Configuration Overview - All config files
• Creating Layouts - Layout design
• Tutorials - Complete setup examples

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:

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

Widget Categories

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

Navigation

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:

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

Widget Interaction

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

Links

If links = true in config:

• Click game objects to interact
• Right-click for context menu

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.

Widget Count

Each widget has rendering overhead. For performance:

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

See Also

• layout.toml Reference - Layout syntax
• Creating Layouts - Design guide
• Performance - Optimization tips

Text Windows

Text windows display scrollable game text. They’re the primary widgets for viewing game output.

Overview

Text windows:

• Display one game stream (main, speech, thoughts, etc.)
• Support scrolling through history
• Apply highlights and colors
• Handle clickable links
• Buffer a configurable number of lines

Configuration

[[windows]]
name = "main"
type = "text"

# Position and size
row = 0
col = 0
width = 80
height = 30

# Text-specific options
stream = "main"           # Game stream to display
buffer_size = 2000        # Maximum lines to keep
word_wrap = true          # Enable word wrapping

# Visual options
show_border = true
border_style = "rounded"
show_title = true
title = "Game"            # Custom title
background_color = "#000000"
text_color = "#CCCCCC"

Properties

stream

The game stream to display:

If not specified, defaults to the widget name.

buffer_size

Maximum lines to keep in memory:

buffer_size = 2000    # Default
buffer_size = 500     # Smaller for secondary windows
buffer_size = 5000    # Large for main window

Older lines are removed when the buffer fills. Larger buffers use more memory.

word_wrap

Whether to wrap long lines:

word_wrap = true      # Wrap at window width (default)
word_wrap = false     # Allow horizontal scrolling

Interaction

Scrolling

Selection

Links

When links = true in config.toml:

Text Styling

Game Colors

The server sends color information through the XML protocol:

• <color fg='...' bg='...'> - Explicit colors
• <preset id='...'> - Named presets (speech, monsterbold)
• <pushBold/><popBold/> - Bold/monsterbold

Highlights

Your highlights.toml patterns are applied after game colors:

[[highlights]]
name = "creatures"
pattern = "goblin|orc"
fg = "#FF6600"
bold = true

Priority

Color priority (highest to lowest):

1. Explicit <color> tags
2. Monsterbold (<pushBold/>)
3. User highlights
4. Preset colors
5. Default text color

Auto-Scroll Behavior

Text windows auto-scroll to show new content when:

• Window is scrolled to the bottom
• New text arrives

Auto-scroll pauses when:

• User scrolls up
• Window is not at bottom

To resume auto-scroll:

• Press End to jump to bottom
• Scroll to the bottom manually

Configure in config.toml:

[behavior]
auto_scroll = true    # Default

Memory Management

Text windows use generation-based change detection for efficient updates:

1. Each add_line() increments a generation counter
2. Sync only copies lines newer than last sync
3. Buffer trimming removes oldest lines when full

This enables smooth performance even with high text throughput.

Examples

Main Game Window

[[windows]]
name = "main"
type = "text"
stream = "main"
row = 0
col = 0
width = "70%"
height = "90%"
buffer_size = 3000
show_title = false
border_style = "rounded"

Speech Window

[[windows]]
name = "speech"
type = "text"
stream = "speech"
row = 0
col = 85
width = 35
height = 15
buffer_size = 500
title = "Speech"

Thoughts Window

[[windows]]
name = "thoughts"
type = "text"
stream = "thoughts"
row = 15
col = 85
width = 35
height = 15
buffer_size = 500
title = "Thoughts"

Minimal (No Border)

[[windows]]
name = "main"
type = "text"
row = 0
col = 0
width = "100%"
height = "100%"
show_border = false
show_title = false
transparent_background = true

Troubleshooting

Text not appearing

1. Check stream matches intended source
2. Verify window is within layout bounds
3. Check enabled = true (default)

Colors wrong

1. Verify COLORTERM=truecolor is set
2. Check highlights aren’t overriding game colors
3. Review preset colors in colors.toml

Performance issues

1. Reduce buffer_size on secondary windows
2. Reduce number of highlight patterns
3. Use fast_parse = true for literal patterns

See Also

• Tabbed Text Windows - Multiple streams in tabs
• Highlight Patterns - Text styling
• Stream Reference - All streams

Tabbed Text Windows

Tabbed text windows combine multiple game streams into a single widget with selectable tabs.

Overview

Tabbed text windows:

• Display multiple streams in one widget
• Switch between tabs to view different content
• Share a single buffer per tab
• Save screen space vs. multiple windows

Configuration

[[windows]]
name = "channels"
type = "tabbed_text"

# Position and size
row = 0
col = 80
width = 40
height = 20

# Tab configuration
tabs = ["speech", "thoughts", "combat"]
default_tab = "speech"
show_tab_bar = true

# Visual options
tab_bar_position = "top"    # "top" or "bottom"
buffer_size = 1000          # Per-tab buffer

Properties

tabs (required)

List of streams to display as tabs:

tabs = ["speech", "thoughts", "combat"]

Each tab shows content from the named stream.

default_tab

Initially selected tab:

default_tab = "speech"    # Open to speech tab

If not specified, opens to first tab.

show_tab_bar

Whether to display the tab bar:

show_tab_bar = true     # Show tabs (default)
show_tab_bar = false    # Hide tab bar

tab_bar_position

Position of the tab bar:

tab_bar_position = "top"      # Tabs at top (default)
tab_bar_position = "bottom"   # Tabs at bottom

buffer_size

Lines to buffer per tab:

buffer_size = 1000    # Default per tab

Tab Bar Display

┌─ Channels ──────────────────────────┐
│ [Speech] [Thoughts] [Combat]        │
├─────────────────────────────────────┤
│ Alice says, "Hello everyone!"       │
│ Bob asks, "How are you?"            │
│ Charlie exclaims, "Great day!"      │
│                                     │
└─────────────────────────────────────┘

Active tab is highlighted, inactive tabs are dimmed.

Interaction

Tab Navigation

Content Navigation

Text Operations

Examples

Communication Channels

[[windows]]
name = "channels"
type = "tabbed_text"
tabs = ["speech", "thoughts", "whisper"]
default_tab = "speech"
row = 0
col = 80
width = 40
height = 20
title = "Channels"

Combat and Notifications

[[windows]]
name = "alerts"
type = "tabbed_text"
tabs = ["combat", "death", "logons"]
default_tab = "combat"
row = 20
col = 80
width = 40
height = 15
title = "Alerts"

All Streams

[[windows]]
name = "all_streams"
type = "tabbed_text"
tabs = ["speech", "thoughts", "combat", "death", "logons", "familiar", "group"]
default_tab = "speech"
row = 0
col = 80
width = 40
height = 35
buffer_size = 500    # Smaller buffer for many tabs

Hidden Tab Bar

[[windows]]
name = "hidden_tabs"
type = "tabbed_text"
tabs = ["speech", "thoughts"]
show_tab_bar = false
row = 0
col = 80
width = 40
height = 20

Use keybinds to switch tabs when bar is hidden.

Tab Indicators

Unread Content

Tabs with new unread content show an indicator:

[Speech*] [Thoughts] [Combat]

The * indicates unread content in that tab.

Activity Highlighting

Active tabs can use different colors:

active_tab_color = "#FFFFFF"
inactive_tab_color = "#808080"
unread_tab_color = "#FFFF00"

Memory Considerations

Each tab maintains its own buffer:

Total memory ≈ buffer_size × number_of_tabs × line_size

For many tabs, reduce buffer_size:

# 7 tabs × 500 lines = 3500 lines total
tabs = ["speech", "thoughts", "combat", "death", "logons", "familiar", "group"]
buffer_size = 500

Stream Reference

Common streams for tabs:

Troubleshooting

Tab not receiving content

1. Verify stream name is correct
2. Check game is sending that stream
3. Some streams require game features

Tabs not switching

1. Ensure widget has focus
2. Check keybinds for conflicts
3. Try clicking tabs directly

Memory issues with many tabs

1. Reduce buffer_size
2. Use fewer tabs
3. Remove unused streams

See Also

• Text Windows - Single stream windows
• Stream Reference - All streams
• Keybinds - Tab navigation keys

Command Input

The command input widget provides the text entry field for sending commands to the game.

Overview

The command input:

• Accepts keyboard input for game commands
• Maintains command history
• Supports editing operations (cut, copy, paste)
• Can display a custom prompt

Configuration

[[windows]]
name = "input"
type = "command_input"

# Position and size
row = 38
col = 0
width = 120
height = 2

# Input-specific options
prompt = "> "             # Input prompt
history = true            # Enable command history
history_size = 1000       # Commands to remember

# Visual options
show_border = true
border_style = "rounded"
background_color = "#0A0A0A"
text_color = "#FFFFFF"
cursor_color = "#FFFFFF"

Properties

prompt

The prompt displayed before input:

prompt = "> "         # Default
prompt = ">> "        # Double arrow
prompt = "[cmd] "     # Custom label
prompt = ""           # No prompt

history

Enable command history:

history = true        # Enable (default)
history = false       # Disable

history_size

Number of commands to remember:

history_size = 1000   # Default
history_size = 100    # Smaller history
history_size = 5000   # Large history

Input Operations

Basic Input

Cursor Movement

Editing

Clipboard

History

Display

Single Line

> look

Standard single-line input.

Multi-Line

[[windows]]
name = "input"
type = "command_input"
height = 3    # Multiple lines visible

Shows more context:

┌─ Input ────────────────────────────┐
│ > look                             │
│                                    │
└────────────────────────────────────┘

No Border

[[windows]]
name = "input"
type = "command_input"
show_border = false
show_title = false
height = 1

Minimal footprint:

> look█

Examples

Standard Input

[[windows]]
name = "input"
type = "command_input"
row = 38
col = 0
width = 120
height = 2
prompt = "> "
history = true
show_border = true
border_style = "rounded"
title = "Command"

Full-Width Minimal

[[windows]]
name = "input"
type = "command_input"
row = 39
col = 0
width = "100%"
height = 1
show_border = false
background_color = "#0A0A0A"

Centered Input

[[windows]]
name = "input"
type = "command_input"
row = 38
col = 20
width = 80
height = 2
prompt = ">> "
border_style = "double"

Command Processing

Command Flow

1. User types command
2. User presses Enter
3. Command added to history
4. Command sent to game server
5. Input cleared for next command

Special Commands

Two-Face intercepts some commands:

History Features

Navigation

• Up cycles through older commands
• Down cycles through newer commands
• Current input is preserved when browsing

Persistence

Command history is saved between sessions in:

~/.two-face/history

Duplicate Handling

Consecutive duplicate commands are not added to history.

Focus Behavior

The command input:

• Automatically receives focus on startup
• Maintains focus during normal gameplay
• Returns focus when popups close
• Can be focused with Ctrl+I or clicking

Troubleshooting

Commands not sending

1. Check input has focus (cursor visible)
2. Verify connection is active
3. Check for keybind conflicts with Enter

History not working

1. Verify history = true
2. Check history_size > 0
3. Check file permissions on history file

Cursor not visible

1. Check cursor_color is visible
2. Verify widget has focus
3. Check width is sufficient

See Also

• Keybinds Configuration - Input shortcuts
• Quick Tour - Basic usage
• Automation - Command automation

Progress Bars

Progress bars display character statistics as visual bars with optional numeric values.

Overview

Progress bars:

• Show health, mana, stamina, spirit, encumbrance
• Update automatically from game data
• Support custom colors and styling
• Can show value, percentage, or both

Configuration

[[windows]]
name = "health"
type = "progress"

# Position and size
row = 0
col = 80
width = 30
height = 1

# Progress-specific options
stat = "health"           # Stat to track (required)
show_value = true         # Show "425/500"
show_percentage = false   # Show "85%"
show_label = true         # Show stat name

# Colors
bar_color = "#00FF00"     # Bar fill color
bar_empty_color = "#333333"  # Empty portion
text_color = "#FFFFFF"    # Text color

Properties

stat (required)

The character statistic to display:

show_value

Display the numeric value:

show_value = true     # Shows "425/500"
show_value = false    # Bar only

show_percentage

Display percentage instead of/with value:

show_percentage = true    # Shows "85%"
show_percentage = false   # Shows value or nothing

show_label

Display the stat name:

show_label = true     # Shows "HP: 425/500"
show_label = false    # Shows "425/500"

bar_color

Color of the filled portion:

bar_color = "#00FF00"     # Green
bar_color = "health"      # From palette
bar_color = "@health"     # From preset

Dynamic Colors

Use different colors based on value:

[[windows]]
name = "health"
type = "progress"
stat = "health"

# Color thresholds (checked in order)
[windows.color_thresholds]
75 = "#00FF00"    # Green above 75%
50 = "#FFFF00"    # Yellow 50-75%
25 = "#FF8800"    # Orange 25-50%
0 = "#FF0000"     # Red below 25%

Display Formats

Compact (1 row)

[[windows]]
name = "health"
type = "progress"
stat = "health"
width = 20
height = 1
show_label = true
show_value = true

Result: HP ████████░░ 80%

Minimal (Bar only)

[[windows]]
name = "health"
type = "progress"
stat = "health"
width = 15
height = 1
show_label = false
show_value = false

Result: ████████████░░░

Vertical Bar

[[windows]]
name = "health"
type = "progress"
stat = "health"
width = 3
height = 10
orientation = "vertical"

Examples

Health Bar (Green)

[[windows]]
name = "health"
type = "progress"
stat = "health"
row = 0
col = 80
width = 25
height = 1
bar_color = "#00FF00"
show_value = true

Mana Bar (Blue)

[[windows]]
name = "mana"
type = "progress"
stat = "mana"
row = 1
col = 80
width = 25
height = 1
bar_color = "#0088FF"
show_value = true

Spirit Bar (Cyan)

[[windows]]
name = "spirit"
type = "progress"
stat = "spirit"
row = 2
col = 80
width = 25
height = 1
bar_color = "#00FFFF"
show_value = true

Stamina Bar (Yellow)

[[windows]]
name = "stamina"
type = "progress"
stat = "stamina"
row = 3
col = 80
width = 25
height = 1
bar_color = "#FFFF00"
show_value = true

Encumbrance Bar

[[windows]]
name = "encumbrance"
type = "progress"
stat = "encumbrance"
row = 4
col = 80
width = 25
height = 1
bar_color = "#888888"
show_percentage = true

Stacked Vitals

# All vitals in one area
[[windows]]
name = "health"
type = "progress"
stat = "health"
row = 0
col = 100
width = 20
height = 1

[[windows]]
name = "mana"
type = "progress"
stat = "mana"
row = 1
col = 100
width = 20
height = 1

[[windows]]
name = "spirit"
type = "progress"
stat = "spirit"
row = 2
col = 100
width = 20
height = 1

[[windows]]
name = "stamina"
type = "progress"
stat = "stamina"
row = 3
col = 100
width = 20
height = 1

Data Source

Progress bars receive data from <progressBar> XML elements:

<progressBar id='health' value='85' text='health 425/500' />

The parser extracts:

• id: Stat type
• value: Percentage (0-100)
• text: Parse current/max values

Troubleshooting

Bar not updating

1. Verify stat matches a valid stat ID
2. Check game is sending progress bar data
3. Ensure widget is enabled

Wrong colors

1. Check bar_color syntax
2. Verify palette/preset references exist
3. Check color threshold order

Value display issues

1. Ensure show_value or show_percentage is true
2. Check width is sufficient for text
3. Verify text_color is visible against background

See Also

• Dashboard - Composite status widget
• Countdowns - RT/cast time display
• Color Configuration - Color settings

Countdowns

Countdown widgets display roundtime and cast time remaining.

Overview

Countdown widgets:

• Show remaining seconds for roundtime or cast time
• Update every second automatically
• Support visual bar and numeric display
• Customize icons and colors

Configuration

[[windows]]
name = "roundtime"
type = "countdown"

# Position and size
row = 5
col = 80
width = 15
height = 1

# Countdown-specific options
countdown_type = "roundtime"  # "roundtime" or "casttime"
show_bar = true               # Show progress bar
show_seconds = true           # Show numeric seconds
icon = "⏱"                    # Icon prefix

# Colors
bar_color = "#FF0000"         # Progress bar color
text_color = "#FFFFFF"        # Seconds text color
background_color = "#000000"

Properties

countdown_type (required)

Which countdown to display:

show_bar

Display a progress bar:

show_bar = true       # Show visual bar (default)
show_bar = false      # Numbers only

show_seconds

Display numeric seconds remaining:

show_seconds = true   # Show "5s" (default)
show_seconds = false  # Bar only

icon

Icon displayed before countdown:

icon = "⏱"        # Timer emoji
icon = "RT:"       # Text prefix
icon = ""          # No icon

Display Modes

Bar with Seconds

⏱ ██████░░░░ 6s

Shows visual progress and numeric value.

Bar Only

██████████░░░░░░░░░░

Clean visual indicator.

Seconds Only

RT: 6

Minimal numeric display.

Compact

width = 8
height = 1
show_bar = false
icon = ""

Result: 6s

Visual Behavior

Active Countdown

When time is remaining:

• Bar fills proportionally
• Seconds count down
• Color indicates urgency

Zero/Expired

When countdown reaches zero:

• Bar empty or hidden
• Shows “0” or disappears
• Can trigger alert

Color Progression

Optional color changes based on time:

# High time (>5s)
high_color = "#00FF00"

# Medium time (2-5s)
medium_color = "#FFFF00"

# Low time (<2s)
low_color = "#FF0000"

Examples

Standard Roundtime

[[windows]]
name = "roundtime"
type = "countdown"
countdown_type = "roundtime"
row = 5
col = 80
width = 20
height = 1
icon = "RT:"
show_bar = true
show_seconds = true
bar_color = "#FF4444"

Cast Time

[[windows]]
name = "casttime"
type = "countdown"
countdown_type = "casttime"
row = 6
col = 80
width = 20
height = 1
icon = "CT:"
show_bar = true
show_seconds = true
bar_color = "#4444FF"

Minimal RT

[[windows]]
name = "rt"
type = "countdown"
countdown_type = "roundtime"
row = 0
col = 0
width = 5
height = 1
icon = ""
show_bar = false
show_border = false
text_color = "#FF0000"

Dual Countdowns

# Side by side
[[windows]]
name = "roundtime"
type = "countdown"
countdown_type = "roundtime"
row = 10
col = 80
width = 15
height = 1
icon = "RT"
bar_color = "#FF0000"

[[windows]]
name = "casttime"
type = "countdown"
countdown_type = "casttime"
row = 10
col = 96
width = 15
height = 1
icon = "CT"
bar_color = "#0088FF"

Progress Bar Style

[[windows]]
name = "roundtime"
type = "countdown"
countdown_type = "roundtime"
row = 15
col = 80
width = 30
height = 1
show_seconds = false
show_border = false
bar_color = "#FF6600"
transparent_background = true

Data Source

Countdown widgets receive data from XML elements:

<roundTime value='1234567890'/>
<castTime value='1234567895'/>

The value is a Unix timestamp when the countdown ends. Two-Face calculates remaining seconds.

Accuracy

Countdowns update based on:

• Game server timestamps
• Local system clock
• ~1 second precision

Minor drift from game may occur due to network latency.

Alerts

Configure alerts when countdown ends:

# In config.toml
[alerts]
roundtime_end_sound = "sounds/ding.wav"
roundtime_end_flash = true

Troubleshooting

Countdown not appearing

1. Check countdown_type is correct
2. Verify game is sending countdown data
3. Actions must trigger roundtime

Time seems wrong

1. Check system clock accuracy
2. Network latency can cause slight drift
3. Verify countdown is for expected action

Bar not showing

1. Check show_bar = true
2. Verify width is sufficient
3. Check bar_color is visible

See Also

• Progress Bars - Static progress display
• Indicators - Status indicators
• Sound Alerts - Alert configuration

Compass

The compass widget displays available room exits as directional indicators.

Overview

The compass:

• Shows all available exits from current room
• Updates automatically when you move
• Supports graphical and text display modes
• Highlights cardinal and special directions

Configuration

[[windows]]
name = "compass"
type = "compass"

# Position and size
row = 0
col = 100
width = 11
height = 5

# Compass-specific options
style = "graphical"       # "graphical" or "text"
show_labels = true        # Show N/S/E/W labels
compact = false           # Compact display mode

# Colors
active_color = "#FFFFFF"  # Available exit color
inactive_color = "#333333"  # Unavailable direction
special_color = "#00FFFF" # Special exits (out, up, down)

Properties

style

Display style:

show_labels

Show direction labels:

show_labels = true    # Shows N, S, E, W, etc.
show_labels = false   # Icons/indicators only

compact

Use compact layout:

compact = false   # Full 5x11 compass (default)
compact = true    # Smaller 3x7 compass

Direction Mapping

The compass recognizes these directions:

Display Modes

Graphical Mode (Default)

    [N]
[NW]   [NE]
[W]  +  [E]
[SW]   [SE]
    [S]

Available exits are highlighted, unavailable are dimmed.

Text Mode

Exits: n, e, sw, out

Simple text list of available directions.

Compact Mode

 N
W+E
 S

Smaller footprint, cardinal directions only.

Examples

Standard Compass

[[windows]]
name = "compass"
type = "compass"
row = 5
col = 100
width = 11
height = 5
style = "graphical"
show_labels = true
border_style = "rounded"
title = "Exits"

Compact Compass

[[windows]]
name = "compass"
type = "compass"
row = 0
col = 110
width = 7
height = 3
style = "graphical"
compact = true
show_border = false

Text List

[[windows]]
name = "exits"
type = "compass"
row = 10
col = 80
width = 25
height = 1
style = "text"
show_border = false

Colored Compass

[[windows]]
name = "compass"
type = "compass"
row = 5
col = 100
width = 11
height = 5
active_color = "#00FF00"      # Green for available
inactive_color = "#1A1A1A"    # Very dark for unavailable
special_color = "#FFFF00"     # Yellow for up/down/out

Interaction

The compass is display-only by default. With links = true:

Data Source

The compass receives data from <compass> XML elements:

<compass>
  <dir value="n"/>
  <dir value="e"/>
  <dir value="out"/>
</compass>

The <nav> element provides additional room information:

<nav rm='123456'/>

Troubleshooting

Compass not updating

1. Verify you’re receiving compass data (check main window)
2. Some areas don’t send compass info
3. Check widget is properly configured

Exits showing incorrectly

1. The game controls compass data
2. Some rooms have unusual exit names
3. Special exits may not appear in compass

Display issues

1. Check width and height are sufficient
2. Verify style matches your preference
3. Check colors are visible against background

See Also

• Room Window - Full room information
• layout.toml Reference - Layout syntax
• Navigation Tutorial - Layout examples

Hands

Hand widgets display items held in your character’s hands and prepared spells.

Overview

Hand widgets:

• Show left hand, right hand, or spell contents
• Update automatically when items change
• Support clickable links to items
• Display custom icons

Configuration

[[windows]]
name = "right_hand"
type = "hand"

# Position and size
row = 10
col = 100
width = 20
height = 1

# Hand-specific options
hand_type = "right"       # "left", "right", or "spell"

# Display options
icon = "🤚"               # Icon before text
icon_color = "#FFFFFF"    # Icon color
text_color = "#CCCCCC"    # Item text color

# Visual options
show_border = true
border_style = "rounded"

Properties

hand_type (required)

Which hand/slot to display:

icon

Icon displayed before content:

# Hand icons
icon = "🤚"       # Generic hand
icon = "👋"       # Wave (left)
icon = "✋"       # Palm (right)
icon = "✨"       # Sparkle (spell)

# Text icons
icon = "[L]"      # Left bracket
icon = "[R]"      # Right bracket
icon = "[S]"      # Spell bracket

# No icon
icon = ""

icon_color

Color of the icon:

icon_color = "#FFFFFF"    # White
icon_color = "bright_cyan"  # Palette color
icon_color = "@links"     # Preset color

text_color

Color of the item text:

text_color = "#CCCCCC"    # Default gray
text_color = "@links"     # Link color from presets

Display Modes

With Icon

🤚 a gleaming vultite sword

Text Only

[R] a gleaming vultite sword

Compact

show_border = false
icon = ""
width = 25
height = 1

Result: a gleaming vultite sword

Interaction

With links = true in config.toml:

Actions depend on the item type:

• Weapons: Attack commands
• Containers: Open/search
• General: Look/inspect

Examples

Right Hand

[[windows]]
name = "right_hand"
type = "hand"
hand_type = "right"
row = 5
col = 80
width = 25
height = 1
icon = "✋"
icon_color = "#AAAAAA"
title = "Right"

Left Hand

[[windows]]
name = "left_hand"
type = "hand"
hand_type = "left"
row = 6
col = 80
width = 25
height = 1
icon = "🤚"
icon_color = "#AAAAAA"
title = "Left"

Spell Hand

[[windows]]
name = "spell"
type = "hand"
hand_type = "spell"
row = 7
col = 80
width = 25
height = 1
icon = "✨"
icon_color = "#FFFF00"
title = "Spell"
text_color = "#FF88FF"

Stacked Hands

# All three hands vertically
[[windows]]
name = "right_hand"
type = "hand"
hand_type = "right"
row = 10
col = 100
width = 20
height = 1
icon = "R:"
show_border = false

[[windows]]
name = "left_hand"
type = "hand"
hand_type = "left"
row = 11
col = 100
width = 20
height = 1
icon = "L:"
show_border = false

[[windows]]
name = "spell"
type = "hand"
hand_type = "spell"
row = 12
col = 100
width = 20
height = 1
icon = "S:"
show_border = false

Bordered Group

[[windows]]
name = "hands"
type = "container"
row = 10
col = 100
width = 22
height = 5
title = "Hands"
border_style = "rounded"

[[windows]]
name = "right_hand"
type = "hand"
hand_type = "right"
row = 11
col = 101
width = 20
height = 1
show_border = false

[[windows]]
name = "left_hand"
type = "hand"
hand_type = "left"
row = 12
col = 101
width = 20
height = 1
show_border = false

[[windows]]
name = "spell"
type = "hand"
hand_type = "spell"
row = 13
col = 101
width = 20
height = 1
show_border = false

Data Source

Hand widgets receive data from XML elements:

<right exist="123456" noun="sword">a gleaming vultite sword</right>
<left exist="789012" noun="shield">a battered wooden shield</left>
<spell>Minor Sanctuary</spell>

The exist and noun attributes enable link functionality.

Empty Hands

When a hand is empty:

• Display shows “Empty” or nothing
• Configure empty display:

empty_text = "Empty"      # Show "Empty"
empty_text = "-"          # Show dash
empty_text = ""           # Show nothing

Troubleshooting

Hand not updating

1. Check hand_type is correct
2. Verify game is sending hand data
3. Check widget is positioned correctly

Links not working

1. Enable links = true in config.toml
2. Verify item has exist ID
3. Check for click handler conflicts

Text truncated

1. Increase widget width
2. Remove icon to save space
3. Use smaller font if available

See Also

• Indicators - Status indicators
• Dashboard - Composite status
• Link Configuration - Link settings

Status Indicators

Status indicator widgets display active character conditions like stunned, hidden, poisoned, etc.

Overview

Indicator widgets:

• Show active status conditions
• Update automatically when conditions change
• Support icon or text display modes
• Can show multiple conditions

Configuration

[[windows]]
name = "status"
type = "indicator"

# Position and size
row = 8
col = 100
width = 20
height = 3

# Indicator-specific options
indicators = ["stunned", "hidden", "webbed", "poisoned"]
style = "icons"           # "icons" or "text"
layout = "horizontal"     # "horizontal" or "vertical"
show_inactive = false     # Show inactive indicators dimmed

# Colors
active_color = "#FF0000"
inactive_color = "#333333"

Properties

indicators

Which conditions to display:

# Show specific indicators
indicators = ["stunned", "hidden", "poisoned"]

# Show all indicators
indicators = "all"

Available indicators:

style

Display style:

style = "icons"     # Show icons (default)
style = "text"      # Show text labels
style = "both"      # Icon and text

layout

Indicator arrangement:

layout = "horizontal"   # Side by side (default)
layout = "vertical"     # Stacked
layout = "grid"         # Grid layout

show_inactive

Whether to show inactive indicators:

show_inactive = false   # Hide inactive (default)
show_inactive = true    # Show dimmed

Display Modes

Icons Only

⚡ 🕸️ ☠️

Compact, visual indicators.

Text Only

STUNNED  WEBBED  POISONED

Clear text labels.

Icons with Text

⚡ Stunned  🕸️ Webbed

Combined display.

Vertical

⚡ Stunned
🕸️ Webbed
☠️ Poisoned

Stacked layout.

Indicator Icons

Default icons for each condition:

Custom Icons

Override default icons:

[indicator_icons]
stunned = "STUN"
hidden = "HIDE"
poisoned = "POIS"

Examples

Combat Status Bar

[[windows]]
name = "combat_status"
type = "indicator"
indicators = ["stunned", "prone", "webbed"]
row = 0
col = 80
width = 30
height = 1
style = "icons"
layout = "horizontal"
active_color = "#FF4444"

Full Status Panel

[[windows]]
name = "status"
type = "indicator"
indicators = "all"
row = 10
col = 100
width = 15
height = 10
style = "text"
layout = "vertical"
show_inactive = true
active_color = "#FF0000"
inactive_color = "#333333"

Compact Icons

[[windows]]
name = "status_icons"
type = "indicator"
indicators = ["stunned", "hidden", "poisoned", "diseased"]
row = 5
col = 110
width = 10
height = 1
style = "icons"
show_border = false

Health Conditions

[[windows]]
name = "health_status"
type = "indicator"
indicators = ["poisoned", "diseased", "bleeding"]
row = 4
col = 80
width = 20
height = 1
style = "both"
active_color = "#FF8800"
title = "Conditions"

Condition Colors

Different colors for different severity:

[indicator_colors]
# Immediate threats (red)
stunned = "#FF0000"
prone = "#FF0000"

# Combat conditions (orange)
webbed = "#FF8800"
bleeding = "#FF8800"

# Health conditions (yellow)
poisoned = "#FFFF00"
diseased = "#FFFF00"

# Status (blue)
hidden = "#0088FF"
kneeling = "#0088FF"
sitting = "#0088FF"

Animation

Indicators can flash or pulse:

# Flash active indicators
flash_active = true
flash_rate = 500        # Milliseconds

# Pulse critical conditions
pulse_critical = true
critical_indicators = ["stunned", "dead"]

Data Source

Indicators receive data from XML elements:

<indicator id="IconSTUNNED" visible="y"/>
<indicator id="IconHIDDEN" visible="n"/>
<indicator id="IconPOISONED" visible="y"/>

The visible attribute determines active state.

Troubleshooting

Indicators not showing

1. Verify condition is actually active
2. Check indicators list includes the condition
3. Ensure show_inactive = false isn’t hiding it

Wrong icons

1. Check style setting
2. Verify icon font support in terminal
3. Use text fallbacks if needed

Layout issues

1. Adjust width and height
2. Change layout mode
3. Reduce number of indicators

See Also

• Injury Doll - Body injury display
• Active Effects - Buff/debuff display
• Progress Bars - Health status

Injury Doll

The injury doll widget displays a visual representation of injuries to different body parts.

Overview

Injury doll widgets:

• Show body part injury severity visually
• Display wounds, scars, and blood loss
• Update as injuries change
• Support multiple display styles

Configuration

[[windows]]
name = "injuries"
type = "injury_doll"

# Position and size
row = 0
col = 100
width = 20
height = 12

# Injury-specific options
style = "ascii"           # "ascii", "simple", "detailed"
show_labels = true        # Show body part names
show_severity = true      # Show injury level numbers
orientation = "vertical"  # "vertical" or "horizontal"

# Colors by severity
healthy_color = "#00FF00"
minor_color = "#FFFF00"
moderate_color = "#FF8800"
severe_color = "#FF0000"
critical_color = "#FF0000"

Properties

style

Display style for the injury doll:

style = "ascii"      # ASCII art body (default)
style = "simple"     # Text list only
style = "detailed"   # Full visual with numbers

show_labels

Display body part names:

show_labels = true    # Show "Head", "Chest", etc.
show_labels = false   # Visual only

show_severity

Display injury severity numbers:

show_severity = true    # Show severity level (1-4)
show_severity = false   # Color-coded only

orientation

Layout orientation:

orientation = "vertical"    # Tall layout (default)
orientation = "horizontal"  # Wide layout

Body Parts

The injury doll tracks these body parts:

Severity Levels

Display Styles

ASCII Art Style

┌─ Injuries ───────────┐
│       ( o o )        │
│         ─┬─          │
│        ──┼──         │
│          │           │
│         / \          │
│        /   \         │
└──────────────────────┘

Body parts are colored by severity.

Simple Text Style

┌─ Injuries ───────────┐
│ Head: Minor          │
│ Chest: Moderate      │
│ Right Arm: Severe    │
│ Left Leg: Minor      │
└──────────────────────┘

Detailed Style

┌─ Injuries ───────────┐
│ HEAD     [████░░] 2  │
│ CHEST    [██████] 3  │
│ R.ARM    [████████] 4│
│ L.LEG    [██░░░░] 1  │
│ BACK     [░░░░░░] 0  │
└──────────────────────┘

Examples

Standard Injury Doll

[[windows]]
name = "injuries"
type = "injury_doll"
row = 0
col = 100
width = 20
height = 12
style = "ascii"
show_labels = true
show_severity = true
border_style = "rounded"

Compact Text List

[[windows]]
name = "injury_list"
type = "injury_doll"
row = 0
col = 100
width = 25
height = 8
style = "simple"
show_severity = true
title = "Wounds"

Minimal Status

[[windows]]
name = "injury_mini"
type = "injury_doll"
row = 0
col = 100
width = 15
height = 5
style = "simple"
show_labels = false
show_severity = false
show_border = false

Wide Layout

[[windows]]
name = "injuries_wide"
type = "injury_doll"
row = 20
col = 0
width = 60
height = 5
style = "detailed"
orientation = "horizontal"

Severity Colors

Customize colors for each severity level:

[[windows]]
name = "injuries"
type = "injury_doll"

# Custom severity colors
[windows.colors]
healthy = "#00FF00"    # Green
minor = "#FFFF00"      # Yellow
moderate = "#FF8800"   # Orange
severe = "#FF4444"     # Red
critical = "#FF0000"   # Bright red
bleeding = "#880000"   # Dark red for blood
scarred = "#808080"    # Gray for scars

Wound Types

Different wound states may display differently:

Animation

Injuries can animate to draw attention:

# Flash critical injuries
flash_critical = true
flash_rate = 500        # Milliseconds

# Pulse bleeding wounds
pulse_bleeding = true

Data Source

Injury data comes from XML elements:

<indicator id="IconBLEEDING" visible="y"/>
<body>
  <part id="head" value="0"/>
  <part id="chest" value="2"/>
  <part id="rightArm" value="3"/>
</body>

The value attribute indicates severity (0-4).

Integration with Other Widgets

Combined with Health Bars

# Health bar
[[windows]]
name = "health"
type = "progress"
source = "health"
row = 0
col = 80
width = 20
height = 1

# Injury doll below
[[windows]]
name = "injuries"
type = "injury_doll"
row = 1
col = 80
width = 20
height = 10

Part of Status Panel

# Status indicators
[[windows]]
name = "status"
type = "indicator"
row = 0
col = 100
width = 20
height = 2

# Injuries below status
[[windows]]
name = "injuries"
type = "injury_doll"
row = 2
col = 100
width = 20
height = 10

Troubleshooting

Injuries not updating

1. Verify receiving body data from game
2. Check window is using correct type
3. Ensure body part IDs match XML

Wrong colors

1. Check severity color configuration
2. Verify theme colors aren’t overriding
3. Test with default colors first

Display too small

1. Increase width and height
2. Try “simple” style for compact spaces
3. Adjust orientation for available space

See Also

• Status Indicators - Status condition display
• Progress Bars - Health/vitals display
• Active Effects - Buff/debuff display

Active Effects

The active effects widget displays current buffs, debuffs, spells, and other timed effects on your character.

Overview

Active effects widgets:

• Show currently active spells and abilities
• Display remaining duration
• Track buff and debuff status
• Update in real-time as effects expire

Configuration

[[windows]]
name = "effects"
type = "active_effects"

# Position and size
row = 0
col = 100
width = 30
height = 15

# Effect display options
show_duration = true       # Show remaining time
show_icons = true          # Show effect icons
sort_by = "duration"       # "duration", "name", "type"
group_by_type = false      # Group buffs/debuffs

# Filter options
show_buffs = true
show_debuffs = true
show_spells = true
show_abilities = true

# Colors
buff_color = "#00FF00"
debuff_color = "#FF0000"
spell_color = "#00FFFF"
expiring_color = "#FFFF00"

Properties

show_duration

Display remaining time for effects:

show_duration = true    # Show "Spirit Shield (2:45)"
show_duration = false   # Show "Spirit Shield" only

show_icons

Display icons for effects:

show_icons = true     # Show icons/symbols
show_icons = false    # Text only

sort_by

How to sort the effect list:

sort_by = "duration"   # Shortest remaining first
sort_by = "name"       # Alphabetical
sort_by = "type"       # Buffs, then debuffs, etc.

group_by_type

Group effects by category:

group_by_type = true    # Separate sections
group_by_type = false   # Single list (default)

Filter Options

Control which effect types to display:

show_buffs = true       # Beneficial effects
show_debuffs = true     # Harmful effects
show_spells = true      # Active spells
show_abilities = true   # Active abilities

Display Format

Standard List

┌─ Active Effects ─────────────┐
│ ✦ Spirit Shield      (5:23)  │
│ ✦ Elemental Defense  (4:15)  │
│ ✦ Haste              (2:30)  │
│ ✧ Poison             (1:45)  │
│ ✦ Minor Sanctuary    (0:58)  │
└──────────────────────────────┘

• ✦ = Buff (beneficial)
• ✧ = Debuff (harmful)

Grouped Display

┌─ Active Effects ─────────────┐
│ BUFFS:                       │
│   Spirit Shield      (5:23)  │
│   Elemental Defense  (4:15)  │
│   Haste              (2:30)  │
│                              │
│ DEBUFFS:                     │
│   Poison             (1:45)  │
└──────────────────────────────┘

Compact Display

┌─ Effects ────────────────────┐
│ Shield:5:23 Defense:4:15     │
│ Haste:2:30 Poison:1:45       │
└──────────────────────────────┘

Effect Types

Duration Display

Time Formats

Expiring Warning

Effects close to expiring can be highlighted:

expiring_threshold = 30    # Seconds before expiring
expiring_color = "#FFFF00" # Yellow warning
expiring_flash = true      # Flash when expiring

Examples

Full Effects Panel

[[windows]]
name = "effects"
type = "active_effects"
row = 0
col = 100
width = 30
height = 20
show_duration = true
show_icons = true
sort_by = "duration"
group_by_type = true
title = "Active Effects"

Buffs Only

[[windows]]
name = "buffs"
type = "active_effects"
row = 0
col = 100
width = 25
height = 10
show_buffs = true
show_debuffs = false
show_spells = true
buff_color = "#00FF00"
title = "Buffs"

Debuff Monitor

[[windows]]
name = "debuffs"
type = "active_effects"
row = 10
col = 100
width = 25
height = 8
show_buffs = false
show_debuffs = true
debuff_color = "#FF4444"
expiring_color = "#FFFF00"
title = "Debuffs"

Compact Status Bar

[[windows]]
name = "effect_bar"
type = "active_effects"
row = 0
col = 50
width = 50
height = 2
show_icons = true
show_duration = false
sort_by = "type"
show_border = false

Spell Timer

[[windows]]
name = "spells"
type = "active_effects"
row = 15
col = 100
width = 25
height = 12
show_buffs = false
show_debuffs = false
show_spells = true
sort_by = "duration"
title = "Active Spells"

Effect Colors

Customize colors by effect type:

[[windows]]
name = "effects"
type = "active_effects"

[windows.colors]
buff = "#00FF00"          # Green
debuff = "#FF0000"        # Red
spell = "#00FFFF"         # Cyan
ability = "#0088FF"       # Blue
item = "#FF00FF"          # Magenta
expiring = "#FFFF00"      # Yellow
permanent = "#FFFFFF"     # White

Severity-Based Colors

For debuffs, color by severity:

[windows.debuff_colors]
minor = "#FFFF00"      # Yellow
moderate = "#FF8800"   # Orange
severe = "#FF0000"     # Red
critical = "#FF0000"   # Bright red + flash

Animation

Expiring Effects

# Flash effects about to expire
flash_expiring = true
flash_threshold = 30      # Seconds
flash_rate = 500          # Milliseconds

# Fade out expired effects
fade_on_expire = true
fade_duration = 1000      # Milliseconds

New Effects

# Highlight newly added effects
highlight_new = true
highlight_duration = 2000  # Milliseconds
highlight_color = "#FFFFFF"

Data Source

Effects are tracked from multiple XML sources:

<spell>Spirit Shield</spell>
<duration value="323"/>

<effect name="Poison" type="debuff" duration="105"/>

<component id="activeSpells">
  Spirit Shield, Elemental Defense
</component>

Integration Examples

Combined with Spell List

# Active effects
[[windows]]
name = "active"
type = "active_effects"
row = 0
col = 100
width = 25
height = 10

# Known spells below
[[windows]]
name = "spells"
type = "spells"
row = 10
col = 100
width = 25
height = 15

Part of Combat Dashboard

# Health/vitals
[[windows]]
name = "vitals"
type = "progress"
row = 0
col = 80
width = 40
height = 4

# Active effects
[[windows]]
name = "effects"
type = "active_effects"
row = 4
col = 80
width = 20
height = 8

# Debuff alerts
[[windows]]
name = "debuffs"
type = "active_effects"
row = 4
col = 100
width = 20
height = 8
show_buffs = false
show_debuffs = true

Troubleshooting

Effects not showing

1. Verify game is sending effect data
2. Check filter settings (show_buffs, etc.)
3. Ensure correct widget type

Duration not updating

1. Effects may not send duration updates
2. Check timer refresh rate
3. Some effects show as permanent

Missing effect types

1. Enable all show_* options to test
2. Check if game sends that effect type
3. Verify effect parsing in logs

See Also

• Spells - Known spell list
• Status Indicators - Status conditions
• Progress Bars - Vitals display
• Countdowns - Timer display

Room Window

The room window displays current room information including name, description, exits, objects, and other players.

Overview

Room windows:

• Show the current room name and description
• Display obvious exits
• List objects and creatures in the room
• Show other players present
• Update when you move

Configuration

[[windows]]
name = "room"
type = "room"

# Position and size
row = 0
col = 80
width = 40
height = 15

# Room-specific options
show_title = true         # Show room name as title
show_description = true   # Show room description
show_exits = true         # Show obvious exits
show_objects = true       # Show items/creatures
show_players = true       # Show other players

# Visual options
title_color = "#FFFFFF"
description_color = "#CCCCCC"
exits_color = "#00FFFF"
objects_color = "#AAAAAA"
players_color = "#00FF00"

Properties

show_title

Display room name as widget title:

show_title = true     # Room name in title bar
show_title = false    # No title/generic title

show_description

Display the room description:

show_description = true    # Full description
show_description = false   # Hide description

show_exits

Display obvious exits:

show_exits = true     # Show "Obvious exits: n, e, out"
show_exits = false    # Hide exits

show_objects

Display items and creatures:

show_objects = true   # Show objects in room
show_objects = false  # Hide objects

show_players

Display other players:

show_players = true   # Show player names
show_players = false  # Hide players

Display Layout

┌─ Town Square Central ───────────────┐
│ This is the heart of the town,      │
│ where merchants hawk their wares    │
│ and travelers gather to share news. │
│                                     │
│ You also see a wooden bench, a      │
│ town crier, and a young squire.     │
│                                     │
│ Also here: Adventurer, Merchant     │
│                                     │
│ Obvious paths: north, east, south,  │
│ west, out                           │
└─────────────────────────────────────┘

Component Colors

Style each component separately:

[[windows]]
name = "room"
type = "room"

# Component colors
[windows.colors]
title = "#9BA2B2"           # Room name
title_bg = "#395573"        # Room name background
description = "#B0B0B0"     # Description text
exits = "#00CCCC"           # Exit directions
objects = "#888888"         # Items/creatures
players = "#00FF00"         # Other players
creatures = "#FF6600"       # Hostile creatures

Examples

Standard Room Window

[[windows]]
name = "room"
type = "room"
row = 0
col = 80
width = 40
height = 15
show_title = true
show_description = true
show_exits = true
show_objects = true
show_players = true
border_style = "rounded"

Compact Room Info

[[windows]]
name = "room"
type = "room"
row = 0
col = 80
width = 40
height = 5
show_description = false   # Hide description
show_objects = false       # Hide objects
show_title = true
show_exits = true
show_players = true

Full Width

[[windows]]
name = "room"
type = "room"
row = 0
col = 0
width = "100%"
height = 8
show_border = false
transparent_background = true

Description Only

[[windows]]
name = "room_desc"
type = "room"
row = 0
col = 80
width = 40
height = 10
show_description = true
show_exits = false
show_objects = false
show_players = false
title = "Description"

Exits Only

[[windows]]
name = "exits"
type = "room"
row = 10
col = 80
width = 40
height = 2
show_description = false
show_objects = false
show_players = false
show_exits = true
show_border = false

Room Components

Room Name

Set by <streamWindow id='room' subtitle='Room Name'/>:

title_color = "#9BA2B2"
title_bg = "#395573"      # Distinct background

Description

Set by <component id='room desc'>:

description_color = "#B0B0B0"
word_wrap = true          # Wrap long descriptions

Exits

Set by <compass> and displayed as text:

exits_color = "#00CCCC"
exits_prefix = "Obvious paths: "

Objects/Creatures

Set by <component id='room objs'>:

objects_color = "#888888"
creature_highlight = true    # Highlight creatures
creature_color = "#FF6600"   # Creature color

Players

Set by <component id='room players'>:

players_color = "#00FF00"
players_prefix = "Also here: "

Interaction

With links = true:

Data Source

Room windows receive data from multiple XML elements:

<streamWindow id='room' subtitle='Town Square'/>
<component id='room desc'>This is the description...</component>
<component id='room objs'>You also see a bench...</component>
<component id='room players'>Also here: Alice, Bob</component>
<compass><dir value='n'/><dir value='e'/></compass>

Troubleshooting

Room not updating

1. Check you’re receiving room data
2. Verify window stream is correct
3. Some areas suppress room info

Missing components

1. Enable specific show_* options
2. Check game is sending that component
3. Verify component colors are visible

Text overflow

1. Increase window height
2. Enable word wrap
3. Hide less important components

See Also

• Compass - Visual exit display
• Text Windows - General text display
• Highlights - Text styling

Inventory Widget

The inventory widget displays your character’s carried items and container contents.

Overview

Inventory widgets:

• Show items in containers (backpack, cloak, etc.)
• Display item counts and descriptions
• Support expandable container trees
• Enable quick item access

Configuration

[[windows]]
name = "inventory"
type = "inventory"

# Position and size
row = 0
col = 80
width = 40
height = 25

# Inventory-specific options
show_containers = true     # Show container hierarchy
expand_containers = false  # Auto-expand all containers
show_count = true          # Show item counts
show_weight = true         # Show weight (if available)
sort_by = "name"           # "name", "type", "none"

# Interaction
clickable = true           # Click to interact
double_click_action = "look"  # "look", "get", "open"

Properties

show_containers

Display container hierarchy:

show_containers = true    # Show nested structure
show_containers = false   # Flat item list

expand_containers

Auto-expand containers:

expand_containers = false   # Collapsed by default
expand_containers = true    # All expanded

show_count

Display item counts:

show_count = true    # "5 silver coins"
show_count = false   # "silver coins"

show_weight

Display item weight (if available):

show_weight = true    # Show weight info
show_weight = false   # Hide weight

sort_by

Item sort order:

sort_by = "name"    # Alphabetical
sort_by = "type"    # By item type
sort_by = "none"    # Game order

Display Format

Tree View

┌─ Inventory ────────────────────────┐
│ ▼ a leather backpack               │
│   ├─ some silver coins (23)        │
│   ├─ a healing potion              │
│   ├─ a bronze lockpick             │
│   └─ ▶ a small pouch               │
│                                    │
│ ▼ a dark cloak                     │
│   ├─ a silver dagger               │
│   └─ a vial of poison              │
│                                    │
│ a sturdy shield                    │
│ a steel longsword                  │
└────────────────────────────────────┘

• ▼ = Expanded container
• ▶ = Collapsed container

Flat View

┌─ Inventory ────────────────────────┐
│ some silver coins (23)             │
│ a healing potion                   │
│ a bronze lockpick                  │
│ a silver dagger                    │
│ a vial of poison                   │
│ a sturdy shield                    │
│ a steel longsword                  │
└────────────────────────────────────┘

Compact View

┌─ Items ───────────┐
│ coins(23) potion  │
│ lockpick dagger   │
│ poison shield     │
│ longsword         │
└───────────────────┘

Examples

Full Inventory Panel

[[windows]]
name = "inventory"
type = "inventory"
row = 0
col = 80
width = 40
height = 30
show_containers = true
expand_containers = false
show_count = true
clickable = true
title = "Inventory"
border_style = "rounded"

Compact Item List

[[windows]]
name = "items"
type = "inventory"
row = 0
col = 100
width = 25
height = 15
show_containers = false
show_count = true
sort_by = "name"
title = "Items"

Container Focus

[[windows]]
name = "backpack"
type = "inventory"
row = 10
col = 80
width = 30
height = 15
container = "backpack"     # Focus on specific container
expand_containers = true
title = "Backpack"

Merchant View

[[windows]]
name = "merchant_inv"
type = "inventory"
row = 0
col = 60
width = 50
height = 35
show_containers = true
expand_containers = true
show_weight = true
sort_by = "type"
clickable = true
double_click_action = "look"

Item Interaction

Click Actions

Context Menu Options

┌────────────────┐
│ Look           │
│ Get            │
│ Drop           │
│ Put in...      │
│ Give to...     │
│ ────────────── │
│ Examine        │
│ Appraise       │
└────────────────┘

Keyboard Navigation

Item Colors

Color items by type or rarity:

[[windows]]
name = "inventory"
type = "inventory"

[windows.item_colors]
weapon = "#FF8800"       # Orange
armor = "#888888"        # Gray
potion = "#00FF00"       # Green
scroll = "#FFFF00"       # Yellow
gem = "#FF00FF"          # Magenta
coin = "#FFD700"         # Gold
container = "#00FFFF"    # Cyan
default = "#FFFFFF"      # White

Rarity Colors

[windows.rarity_colors]
common = "#FFFFFF"       # White
uncommon = "#00FF00"     # Green
rare = "#0088FF"         # Blue
epic = "#FF00FF"         # Purple
legendary = "#FFD700"    # Gold

Container Options

Specific Container

Focus on a single container:

container = "backpack"    # Only show backpack contents
container = "cloak"       # Only show cloak contents

Container Depth

Limit nesting depth:

max_depth = 2    # Only show 2 levels deep
max_depth = 0    # Show all levels (default)

Auto-Refresh

auto_refresh = true       # Update when inventory changes
refresh_rate = 1000       # Milliseconds (if polling)

Data Source

Inventory data comes from XML elements:

<inv id="stow">
  <item>a leather backpack</item>
  <item>a dark cloak</item>
</inv>

<container id="backpack">
  <item>some silver coins</item>
  <item>a healing potion</item>
</container>

Integration Examples

With Hands Display

# What you're holding
[[windows]]
name = "hands"
type = "hand"
row = 0
col = 80
width = 30
height = 3

# Full inventory below
[[windows]]
name = "inventory"
type = "inventory"
row = 3
col = 80
width = 30
height = 20

Merchant Layout

# Your inventory (left)
[[windows]]
name = "my_items"
type = "inventory"
row = 0
col = 0
width = 40
height = 30
title = "Your Items"

# Merchant inventory (right)
[[windows]]
name = "merchant"
type = "text"
stream = "merchant"
row = 0
col = 50
width = 40
height = 30
title = "Merchant"

Quick Access Bar

# Horizontal quick items
[[windows]]
name = "quick_items"
type = "inventory"
row = 0
col = 0
width = 80
height = 3
show_containers = false
sort_by = "type"
layout = "horizontal"

Weight Tracking

If weight tracking is enabled:

┌─ Inventory ────────────────────────┐
│ Carried: 45.2 lbs / 100 lbs        │
│ ──────────────────────────────────│
│ ▼ leather backpack (12.5 lbs)      │
│   ├─ silver coins (2.3 lbs)        │
│   └─ healing potion (0.5 lbs)      │
└────────────────────────────────────┘

show_weight = true
show_encumbrance = true
encumbrance_warning = 80    # Warn at 80% capacity

Troubleshooting

Inventory not updating

1. Verify receiving inventory data
2. Check window is correct type
3. Try manual refresh command

Containers not expanding

1. Check expand_containers setting
2. Verify container data is being sent
3. Click expand arrow manually

Missing items

1. Check container filter settings
2. Verify all containers are included
3. Check item parsing in debug log

Performance with large inventory

1. Set expand_containers = false
2. Reduce max_depth
3. Focus on specific containers

See Also

• Hands - Held items display
• Room Window - Room objects
• Text Windows - General text display

Spells Widget

The spells widget displays your character’s known spells, spell preparation status, and casting availability.

Overview

Spells widgets:

• List known spells and abilities
• Show spell preparation status
• Display mana costs and cooldowns
• Enable quick spell casting

Configuration

[[windows]]
name = "spells"
type = "spells"

# Position and size
row = 0
col = 100
width = 30
height = 20

# Spell display options
show_prepared = true       # Show preparation status
show_cost = true           # Show mana cost
show_circle = true         # Show spell circle
group_by_circle = true     # Group by spell circle
sort_by = "circle"         # "circle", "name", "cost"

# Interaction
clickable = true           # Click to cast
show_tooltip = true        # Show spell info on hover

# Colors
prepared_color = "#00FF00"
unprepared_color = "#808080"
unavailable_color = "#FF0000"

Properties

show_prepared

Display spell preparation status:

show_prepared = true    # Show ✓/✗ for prepared
show_prepared = false   # List only

show_cost

Display mana cost:

show_cost = true     # Show "(5 mana)"
show_cost = false    # Name only

show_circle

Display spell circle number:

show_circle = true    # Show circle/level
show_circle = false   # Hide circle

group_by_circle

Group spells by circle:

group_by_circle = true    # Sections by circle
group_by_circle = false   # Single list

sort_by

Sort order for spells:

sort_by = "circle"   # By spell circle
sort_by = "name"     # Alphabetical
sort_by = "cost"     # By mana cost

Display Format

Grouped by Circle

┌─ Spells ─────────────────────────┐
│ ─── Minor Spirit (100s) ───      │
│ ✓ Spirit Warding I        (1)    │
│ ✓ Spirit Defense II       (2)    │
│ ✗ Spirit Fog              (6)    │
│                                  │
│ ─── Major Spirit (200s) ───      │
│ ✓ Spirit Shield           (3)    │
│ ✗ Elemental Defense       (5)    │
└──────────────────────────────────┘

Simple List

┌─ Spells ─────────────────────────┐
│ ✓ Spirit Warding I        (1)    │
│ ✓ Spirit Defense II       (2)    │
│ ✓ Spirit Shield           (3)    │
│ ✗ Elemental Defense       (5)    │
│ ✗ Spirit Fog              (6)    │
└──────────────────────────────────┘

Compact Format

┌─ Spells ──────────────┐
│ 101✓ 102✓ 103✗ 104✓   │
│ 201✓ 202✗ 203✓ 204✗   │
└───────────────────────┘

Spell Status

Examples

Full Spell Panel

[[windows]]
name = "spells"
type = "spells"
row = 0
col = 100
width = 35
height = 25
show_prepared = true
show_cost = true
show_circle = true
group_by_circle = true
clickable = true
title = "Known Spells"

Compact Spell Bar

[[windows]]
name = "spell_bar"
type = "spells"
row = 0
col = 50
width = 40
height = 3
group_by_circle = false
show_cost = false
layout = "horizontal"
show_border = false

Prepared Spells Only

[[windows]]
name = "prepared"
type = "spells"
row = 10
col = 100
width = 25
height = 10
filter = "prepared"    # Only show prepared
show_prepared = false  # No status icon needed
title = "Ready Spells"

Quick Cast Panel

[[windows]]
name = "quick_cast"
type = "spells"
row = 0
col = 100
width = 20
height = 15
favorite_spells = [101, 103, 107, 201, 206]
clickable = true
double_click_action = "cast"
title = "Quick Cast"

Spell Interaction

Click Actions

Context Menu

┌────────────────────┐
│ Cast               │
│ Prepare            │
│ ────────────────── │
│ Spell Info         │
│ Show Incantation   │
│ ────────────────── │
│ Add to Quick Cast  │
│ Set Hotkey         │
└────────────────────┘

Keyboard Shortcuts

Spell Colors

Color spells by type or circle:

[[windows]]
name = "spells"
type = "spells"

[windows.spell_colors]
minor_spirit = "#00FFFF"    # Cyan (100s)
major_spirit = "#0088FF"    # Blue (200s)
cleric = "#FFFFFF"          # White (300s)
minor_elemental = "#FF8800" # Orange (400s)
major_elemental = "#FF0000" # Red (500s)
ranger = "#00FF00"          # Green (600s)
sorcerer = "#FF00FF"        # Purple (700s)
wizard = "#FFFF00"          # Yellow (900s)

Status Colors

[windows.status_colors]
prepared = "#00FF00"        # Green
unprepared = "#808080"      # Gray
casting = "#00FFFF"         # Cyan
cooldown = "#FFFF00"        # Yellow
unavailable = "#FF0000"     # Red
insufficient_mana = "#FF8800" # Orange

Mana Cost Display

Show mana costs with current mana:

show_cost = true
show_current_mana = true   # Show current/max
highlight_affordable = true # Dim unaffordable

┌─ Spells ─────────────────────────┐
│ Mana: 45/100                     │
│ ──────────────────────────────── │
│ ✓ Spirit Shield           (3)   │
│ ✓ Elemental Defense       (5)   │
│ ✗ Major Sanctuary        (50)   │  ← Dimmed (can't afford)
└──────────────────────────────────┘

Cooldown Display

Show cooldown timers:

show_cooldowns = true
cooldown_format = "remaining"   # "remaining", "ready_at", "bar"

┌─ Spells ─────────────────────────┐
│ ✓ Spirit Shield           Ready  │
│ ⏱ Mass Sanctuary         (0:45)  │
│ ⏱ Divine Intervention    (2:30)  │
└──────────────────────────────────┘

Data Source

Spell data comes from XML elements:

<spellList>
  <spell id="101" name="Spirit Warding I" prepared="y"/>
  <spell id="102" name="Spirit Barrier" prepared="n"/>
</spellList>

<spell>Spirit Shield</spell>
<duration value="300"/>

Integration Examples

With Active Effects

# Active spells/effects
[[windows]]
name = "active"
type = "active_effects"
row = 0
col = 100
width = 25
height = 10
title = "Active"

# Known spells below
[[windows]]
name = "spells"
type = "spells"
row = 10
col = 100
width = 25
height = 20
title = "Spells"

Combat Spell Panel

# Mana bar
[[windows]]
name = "mana"
type = "progress"
source = "mana"
row = 0
col = 80
width = 30
height = 1

# Offensive spells
[[windows]]
name = "attack_spells"
type = "spells"
row = 1
col = 80
width = 15
height = 10
filter_circles = [400, 500, 700]
title = "Attack"

# Defensive spells
[[windows]]
name = "defense_spells"
type = "spells"
row = 1
col = 95
width = 15
height = 10
filter_circles = [100, 200, 300]
title = "Defense"

Troubleshooting

Spells not showing

1. Verify spell list data is being received
2. Check filter settings
3. Ensure widget type is correct

Preparation status wrong

1. Check game is sending status updates
2. Verify spell ID matching
3. Manual refresh may help

Can’t click to cast

1. Verify clickable = true
2. Check double_click_action setting
3. Ensure widget has focus

Missing spell circles

1. Check filter_circles setting
2. Verify all circles are enabled
3. Check data parsing

See Also

• Active Effects - Active spell display
• Progress Bars - Mana display
• Hands - Spell hand display
• Countdowns - Cast time display

Dashboard Widget

The dashboard widget combines multiple data displays into a single composite panel, providing an at-a-glance overview of character status.

Overview

Dashboard widgets:

• Combine multiple metrics in one widget
• Provide compact status overview
• Reduce window count
• Customizable component selection

Configuration

[[windows]]
name = "dashboard"
type = "dashboard"

# Position and size
row = 0
col = 0
width = 40
height = 15

# Components to include
components = [
    "vitals",
    "experience",
    "stance",
    "encumbrance",
    "wounds"
]

# Layout
layout = "vertical"       # "vertical", "horizontal", "grid"
compact = false           # Condensed display

# Visual options
show_labels = true
show_dividers = true

Properties

components

Which status elements to display:

# Full dashboard
components = [
    "vitals",       # Health, mana, stamina, spirit
    "experience",   # XP info
    "stance",       # Combat stance
    "encumbrance",  # Weight carried
    "wounds",       # Injury summary
    "status",       # Status indicators
    "wealth",       # Silver/gold
    "position"      # Standing/sitting/etc.
]

# Minimal dashboard
components = ["vitals", "stance"]

layout

Component arrangement:

layout = "vertical"     # Stacked top to bottom
layout = "horizontal"   # Side by side
layout = "grid"         # 2-column grid

compact

Condensed display mode:

compact = false   # Full labels and spacing
compact = true    # Minimal spacing, abbreviations

show_labels

Display component labels:

show_labels = true    # "Health: 100/100"
show_labels = false   # "100/100"

show_dividers

Display lines between components:

show_dividers = true    # Lines between sections
show_dividers = false   # No dividers

Available Components

vitals

Health, mana, stamina, spirit bars:

Health:  [████████████████░░░░] 80%
Mana:    [████████████░░░░░░░░] 60%
Stamina: [██████████████████░░] 90%
Spirit:  [████████████████████] 100%

experience

Experience and level info:

Level: 42
Exp: 12,345,678 / 15,000,000
Mind: Clear

stance

Combat stance display:

Stance: Offensive (100/80)

encumbrance

Weight and capacity:

Encumbrance: 45.2 / 100 lbs (45%)

wounds

Injury summary:

Wounds: Head(1) Chest(2) RArm(3)

status

Active status conditions:

Status: Stunned, Poisoned

wealth

Currency display:

Silver: 12,345

position

Character position:

Position: Standing

roundtime

Current roundtime:

RT: 3 seconds

target

Current target:

Target: a massive troll

Display Formats

Standard Vertical

┌─ Dashboard ──────────────────────┐
│ Health:  [████████░░] 80/100     │
│ Mana:    [██████░░░░] 60/100     │
│ Stamina: [█████████░] 90/100     │
│ ──────────────────────────────── │
│ Level 42 | Mind: Clear           │
│ Exp: 12.3M / 15M                 │
│ ──────────────────────────────── │
│ Stance: Offensive (100/80)       │
│ Position: Standing               │
│ ──────────────────────────────── │
│ Wounds: None                     │
│ Status: Clear                    │
└──────────────────────────────────┘

Compact Horizontal

┌─ Status ─────────────────────────────────────────────┐
│ HP:80% MP:60% ST:90% | L42 | Off(100/80) | Standing  │
└──────────────────────────────────────────────────────┘

Grid Layout

┌─ Dashboard ──────────────────────┐
│ Health:  80% │ Level: 42         │
│ Mana:    60% │ Mind: Clear       │
│ Stamina: 90% │ Exp: 12.3M        │
│ ─────────────┼────────────────── │
│ Stance: Off  │ Position: Stand   │
│ RT: 0        │ Silver: 12,345    │
└──────────────────────────────────┘

Examples

Full Status Dashboard

[[windows]]
name = "dashboard"
type = "dashboard"
row = 0
col = 80
width = 40
height = 20
components = [
    "vitals",
    "experience",
    "stance",
    "encumbrance",
    "wounds",
    "status",
    "wealth",
    "position"
]
layout = "vertical"
show_dividers = true
title = "Character Status"

Combat Dashboard

[[windows]]
name = "combat_dash"
type = "dashboard"
row = 0
col = 80
width = 35
height = 12
components = [
    "vitals",
    "stance",
    "roundtime",
    "target",
    "wounds"
]
layout = "vertical"
compact = true
title = "Combat"

Minimal Status Bar

[[windows]]
name = "status_bar"
type = "dashboard"
row = 0
col = 0
width = 80
height = 2
components = ["vitals", "stance", "roundtime"]
layout = "horizontal"
compact = true
show_border = false
show_dividers = false

Experience Focus

[[windows]]
name = "exp_dash"
type = "dashboard"
row = 10
col = 100
width = 25
height = 8
components = ["experience", "wealth"]
layout = "vertical"
title = "Progress"

Hunting Dashboard

[[windows]]
name = "hunting"
type = "dashboard"
row = 0
col = 80
width = 40
height = 15
components = [
    "vitals",
    "stance",
    "wounds",
    "target",
    "roundtime",
    "encumbrance"
]
layout = "grid"
compact = false
title = "Hunting Status"

Component Colors

Customize colors for each component:

[[windows]]
name = "dashboard"
type = "dashboard"

[windows.colors]
# Vital bar colors
health = "#FF0000"
mana = "#0088FF"
stamina = "#00FF00"
spirit = "#FFFF00"

# Status colors
wounded = "#FF8800"
stunned = "#FF0000"
hidden = "#00FFFF"

# Text colors
labels = "#808080"
values = "#FFFFFF"
dividers = "#404040"

Threshold Colors

Change colors based on values:

[windows.health_thresholds]
high = "#00FF00"      # > 75%
medium = "#FFFF00"    # 25-75%
low = "#FF8800"       # 10-25%
critical = "#FF0000"  # < 10%

Data Sources

Dashboard pulls from multiple XML sources:

<dialogData id="health" text="80/100"/>
<dialogData id="mana" text="60/100"/>
<dialogData id="stamina" text="90/100"/>
<dialogData id="spirit" text="100/100"/>

<dialogData id="stance" text="offensive"/>
<indicator id="IconSTANDING" visible="y"/>

<exp>12345678</exp>
<nextExp>15000000</nextExp>

Building Custom Dashboards

Selective Components

Only include what you need:

# Minimalist - just vitals
components = ["vitals"]

# Combat-focused
components = ["vitals", "stance", "wounds", "roundtime"]

# Exploration-focused
components = ["vitals", "encumbrance", "position"]

# Progression-focused
components = ["experience", "wealth"]

Multiple Dashboards

Use different dashboards for different activities:

# Main status (always visible)
[[windows]]
name = "main_dash"
type = "dashboard"
row = 0
col = 80
width = 40
height = 8
components = ["vitals", "stance"]

# Combat details (show during hunting)
[[windows]]
name = "combat_dash"
type = "dashboard"
row = 8
col = 80
width = 40
height = 10
components = ["wounds", "target", "roundtime"]
visible = false  # Toggle via keybind

Troubleshooting

Components not showing

1. Verify component name is correct
2. Check game is sending that data
3. Ensure dashboard has sufficient size

Layout looks wrong

1. Adjust width/height for layout type
2. Try different layout option
3. Enable/disable compact mode

Data not updating

1. Verify XML data is being received
2. Check component is correctly configured
3. Test individual widgets for same data

Performance issues

1. Reduce number of components
2. Use compact mode
3. Increase refresh interval

See Also

• Progress Bars - Individual vital displays
• Status Indicators - Status condition display
• Injury Doll - Wound display
• Performance - Performance metrics

Performance Monitor

The performance widget displays real-time performance metrics for debugging and optimization.

Overview

The performance widget shows:

• Frame rate (FPS)
• Frame timing statistics
• Network throughput
• Parser performance
• Memory usage
• Application uptime

Configuration

[[windows]]
name = "performance"
type = "performance"

# Position and size
row = 0
col = 0
width = 35
height = 15

# Which metrics to display
show_fps = true
show_frame_times = true
show_render_times = true
show_ui_times = false
show_wrap_times = false
show_net = true
show_parse = true
show_events = false
show_memory = true
show_lines = true
show_uptime = true
show_jitter = false
show_frame_spikes = false
show_event_lag = false
show_memory_delta = false

Metric Options

Frame Metrics

Render Metrics

Network Metrics

Parser Metrics

Event Metrics

Memory Metrics

General

Display Example

┌─ Performance ──────────────────────┐
│ FPS: 60.0                          │
│ Frame: 0.8/1.2/2.1 ms              │
│ Render: 0.6 ms                     │
│                                    │
│ Net In: 1.2 KB/s                   │
│ Net Out: 0.1 KB/s                  │
│                                    │
│ Parse: 45 µs (12/s)                │
│                                    │
│ Memory: ~2.4 MB                    │
│ Lines: 12,345                      │
│                                    │
│ Uptime: 01:23:45                   │
└────────────────────────────────────┘

Examples

Full Metrics

[[windows]]
name = "performance"
type = "performance"
row = 0
col = 0
width = 35
height = 18
show_fps = true
show_frame_times = true
show_render_times = true
show_ui_times = true
show_wrap_times = true
show_net = true
show_parse = true
show_events = true
show_memory = true
show_lines = true
show_uptime = true
show_jitter = true
show_frame_spikes = true

Minimal FPS

[[windows]]
name = "fps"
type = "performance"
row = 0
col = 0
width = 15
height = 1
show_fps = true
show_frame_times = false
show_render_times = false
show_net = false
show_parse = false
show_memory = false
show_lines = false
show_uptime = false
show_border = false

Network Focus

[[windows]]
name = "network"
type = "performance"
row = 0
col = 100
width = 20
height = 5
show_fps = false
show_net = true
show_parse = true
show_memory = false
title = "Network"

Memory Focus

[[windows]]
name = "memory"
type = "performance"
row = 5
col = 100
width = 20
height = 5
show_fps = false
show_net = false
show_memory = true
show_lines = true
show_memory_delta = true
title = "Memory"

Metric Details

FPS (Frames Per Second)

FPS: 60.0

Target is 60 FPS. Lower values indicate performance issues.

Frame Times

Frame: 0.8/1.2/2.1 ms

Shows min/avg/max frame time over recent samples. Lower is better.

Frame Jitter

Jitter: 0.3 ms

Standard deviation of frame times. Lower means smoother animation.

Frame Spikes

Spikes: 2

Count of frames taking >33ms (below 30 FPS). Should be 0 or very low.

Render Time

Render: 0.6 ms

Time spent rendering all widgets. Should be well under 16ms.

Network

Net In: 1.2 KB/s
Net Out: 0.1 KB/s

Network throughput. High values during combat/activity are normal.

Parse Time

Parse: 45 µs (12/s)

Average XML parse time and chunks processed per second.

Memory

Memory: ~2.4 MB
Lines: 12,345

Estimated memory usage and total lines in all buffers.

Uptime

Uptime: 01:23:45

Time since Two-Face started (HH:MM:SS).

Performance Overhead

The performance widget itself has minimal overhead:

• Only enabled metrics are collected
• Collection can be disabled entirely

# In config.toml
[performance]
collect_metrics = false   # Disable all collection

Troubleshooting Performance

Low FPS

1. Reduce buffer sizes in text windows
2. Disable unused widgets
3. Reduce highlight pattern count
4. Use fast_parse = true for highlights

High Memory

1. Reduce buffer_size on windows
2. Close unused tabs
3. Check for memory leaks (rising delta)

Network Issues

1. Check connection stability
2. Monitor for packet loss
3. Consider bandwidth limitations

See Also

• Performance Optimization - Optimization guide
• Configuration - Performance settings
• Troubleshooting - Performance fixes

Customization Overview

Two-Face is highly customizable, allowing you to tailor every aspect of your gameplay experience.

Customization Areas

Two-Face can be customized in these areas:

Quick Customization Commands

Customization Guides

This section covers:

• Creating Layouts - Design your window arrangement
• Creating Themes - Customize colors and styling
• Highlight Patterns - Advanced text matching
• Keybind Actions - All available actions
• Sound Alerts - Audio notifications
• TTS Setup - Text-to-speech configuration

Per-Character Customization

Each character can have unique settings:

~/.two-face/
├── config.toml              # Global defaults
├── layout.toml              # Default layout
├── colors.toml              # Default colors
├── highlights.toml          # Default highlights
├── keybinds.toml            # Default keybinds
└── characters/
    └── MyCharacter/
        ├── layout.toml      # Character-specific layout
        ├── colors.toml      # Character-specific colors
        ├── highlights.toml  # Character-specific highlights
        └── keybinds.toml    # Character-specific keybinds

Configuration Loading Order

1. Character-specific file (if exists)
2. Global file (fallback)
3. Embedded defaults (final fallback)

Example: Profession-Based Layouts

Create different layouts for different professions:

~/.two-face/characters/
├── Warrior/
│   └── layout.toml    # Combat-focused layout
├── Empath/
│   └── layout.toml    # Healing-focused layout
└── Wizard/
    └── layout.toml    # Spell-focused layout

Hot-Reloading

Many settings can be reloaded without restarting:

Backup Your Customizations

Before major changes:

# Backup all configuration
cp -r ~/.two-face ~/.two-face-backup

# Backup specific file
cp ~/.two-face/layout.toml ~/.two-face/layout.toml.bak

Sharing Customizations

Share your configurations with others:

1. Export relevant .toml files
2. Share via GitHub Gist, Discord, etc.
3. Others can copy to their ~/.two-face/ directory

Popular Layout Packs

The Two-Face community shares layout packs:

• Hunting layouts
• Merchant layouts
• Roleplay layouts
• Accessibility layouts

Customization Tips

Start Simple

Begin with default settings and customize incrementally:

1. Play with defaults for a few sessions
2. Identify pain points
3. Make one change at a time
4. Test each change before moving on

Use the Editors

The built-in editors are often easier than editing files:

.layout          # Visual layout editor
.highlights      # Browse and edit highlights
.keybinds        # Browse and edit keybinds
.window main     # Edit main window properties

Keep Notes

Document your customizations:

# In any .toml file, add comments:

# Combat creature highlighting
# Red for dangerous, orange for normal
[creature_dangerous]
pattern = "(?i)\\b(dragon|lich|demon)\\b"
fg = "#FF0000"

Test in Safe Areas

Test new configurations in safe game areas before combat:

1. Make changes
2. Reload: .reload highlights
3. Test with game output
4. Adjust as needed

See Also

• Configuration Files - File reference
• Widgets Reference - Widget options
• Tutorials - Step-by-step guides

Creating Layouts

Layouts define the arrangement of widgets on your screen. This guide walks you through creating custom layouts.

Layout Basics

A layout is a collection of window definitions in layout.toml:

[[windows]]
name = "main"
type = "text"
row = 0
col = 0
width = 80
height = 40
streams = ["main", "death"]

[[windows]]
name = "health"
type = "progress"
source = "health"
row = 0
col = 80
width = 30
height = 1

Coordinate System

Two-Face uses a row/column grid:

(0,0)────────────────────────→ col
│
│    ┌─────────────┐
│    │  Widget     │
│    │  row=5      │
│    │  col=10     │
│    └─────────────┘
│
↓ row

• row - Vertical position (0 = top)
• col - Horizontal position (0 = left)
• width - Widget width in columns
• height - Widget height in rows

Percentage-Based Sizing

Use percentages for responsive layouts:

[[windows]]
name = "main"
type = "text"
row = 0
col = 0
width = "60%"    # 60% of screen width
height = "100%"  # Full screen height

[[windows]]
name = "sidebar"
type = "text"
row = 0
col = "60%"      # Start at 60% from left
width = "40%"    # Remaining 40%
height = "100%"

Layout Planning

Step 1: Sketch Your Layout

Draw your desired layout on paper or in a text editor:

┌─────────────────────┬──────────────┐
│                     │   Health     │
│                     ├──────────────┤
│    Main Window      │   Mana       │
│                     ├──────────────┤
│                     │   Compass    │
│                     ├──────────────┤
│                     │   Room       │
├─────────────────────┴──────────────┤
│         Command Input              │
└────────────────────────────────────┘

Step 2: Calculate Dimensions

Determine sizes based on your terminal:

Terminal: 120 columns × 40 rows

Main window: 80 cols × 35 rows (0,0)
Sidebar: 40 cols × 35 rows (0,80)
Command: 120 cols × 5 rows (35,0)

Step 3: Define Windows

Create layout.toml:

# Main game window
[[windows]]
name = "main"
type = "text"
row = 0
col = 0
width = 80
height = 35
streams = ["main", "death"]
buffer_size = 2000

# Health bar
[[windows]]
name = "health"
type = "progress"
source = "health"
row = 0
col = 80
width = 40
height = 1

# Mana bar
[[windows]]
name = "mana"
type = "progress"
source = "mana"
row = 1
col = 80
width = 40
height = 1

# Compass
[[windows]]
name = "compass"
type = "compass"
row = 3
col = 80
width = 20
height = 5

# Room info
[[windows]]
name = "room"
type = "room"
row = 8
col = 80
width = 40
height = 15

# Command input
[[windows]]
name = "input"
type = "command_input"
row = 35
col = 0
width = 120
height = 5

Common Layout Patterns

Full-Width Main

[[windows]]
name = "main"
type = "text"
row = 0
col = 0
width = "100%"
height = "90%"

[[windows]]
name = "input"
type = "command_input"
row = "90%"
col = 0
width = "100%"
height = "10%"

Side Panel

[[windows]]
name = "main"
type = "text"
row = 0
col = 0
width = "70%"
height = "100%"

[[windows]]
name = "sidebar"
type = "tabbed_text"
row = 0
col = "70%"
width = "30%"
height = "100%"
tabs = ["speech", "thoughts", "combat"]

Three-Column

# Left column - Status
[[windows]]
name = "status"
type = "dashboard"
row = 0
col = 0
width = "20%"
height = "100%"

# Center column - Main
[[windows]]
name = "main"
type = "text"
row = 0
col = "20%"
width = "50%"
height = "100%"

# Right column - Info
[[windows]]
name = "info"
type = "tabbed_text"
row = 0
col = "70%"
width = "30%"
height = "100%"

Top/Bottom Split

# Main game (top 70%)
[[windows]]
name = "main"
type = "text"
row = 0
col = 0
width = "100%"
height = "70%"

# Combat log (bottom 30%)
[[windows]]
name = "combat"
type = "text"
row = "70%"
col = 0
width = "100%"
height = "30%"
streams = ["combat"]

Widget Types

Choose the right widget type for each purpose:

Window Properties

Common Properties

[[windows]]
name = "example"          # Unique name (required)
type = "text"             # Widget type (required)
row = 0                   # Position
col = 0
width = 40
height = 20

# Visual
title = "My Window"       # Custom title
show_title = true         # Show title bar
show_border = true        # Show border
border_style = "rounded"  # plain, rounded, double

# Colors
bg_color = "#000000"
text_color = "#FFFFFF"
border_color = "#00FFFF"

# Behavior
visible = true            # Initially visible
focusable = true          # Can receive focus

Text Window Properties

[[windows]]
name = "main"
type = "text"
streams = ["main"]        # Stream IDs to display
buffer_size = 1000        # Max lines to keep
wordwrap = true           # Wrap long lines
timestamps = false        # Show timestamps

Progress Bar Properties

[[windows]]
name = "health"
type = "progress"
source = "health"         # health, mana, spirit, stamina
show_label = true         # Show "Health"
show_numbers = true       # Show "85/100"
show_percent = false      # Show "85%"
bar_color = "#FF0000"

Using the Layout Editor

The built-in editor is often easier:

.layout

Features:

• Visual widget placement
• Drag to reposition
• Resize handles
• Property editing
• Live preview

Testing Your Layout

Quick Test

1. Save layout.toml
2. Run .reload layout
3. Check appearance
4. Adjust and repeat

Terminal Size Testing

Test at different sizes:

# Resize terminal and reload
resize -s 30 80    # Small
.reload layout

resize -s 40 120   # Medium
.reload layout

resize -s 50 160   # Large
.reload layout

Troubleshooting

Overlapping Windows

Windows are drawn in order. Later windows cover earlier ones:

# Background windows first
[[windows]]
name = "background"
# ...

# Foreground windows last
[[windows]]
name = "overlay"
# ...

Windows Cut Off

Check terminal size vs layout dimensions:

# Use percentages for safety
width = "50%"   # Instead of: width = 80

# Or check minimum sizes
min_width = 20
min_height = 5

Responsive Issues

Test with percentages:

# Good: Adapts to terminal size
row = 0
col = "60%"
width = "40%"
height = "100%"

# Risky: Fixed size may not fit
row = 0
col = 100
width = 60
height = 50

Layout Examples

Minimalist

[[windows]]
name = "main"
type = "text"
row = 0
col = 0
width = "100%"
height = "95%"
show_border = false

[[windows]]
name = "input"
type = "command_input"
row = "95%"
col = 0
width = "100%"
height = "5%"
show_border = false

Information Dense

See the Hunting Setup Tutorial for a complex combat layout.

Roleplay Focused

See the Roleplay Setup Tutorial for a communication-focused layout.

See Also

• Layout Configuration - Full reference
• Widgets Reference - All widget types
• Your First Layout - Tutorial

Creating Themes

Themes control colors throughout Two-Face. This guide shows how to create custom color schemes.

Theme Basics

Themes are defined in colors.toml:

# UI Colors
[ui]
text_color = "#FFFFFF"
background_color = "#000000"
border_color = "#00FFFF"
focused_border_color = "#FFFF00"

# Text Presets
[presets.speech]
fg = "#53a684"

[presets.monsterbold]
fg = "#a29900"

Color Formats

Two-Face supports multiple color formats:

UI Colors

Configuration

[ui]
# Text
text_color = "#FFFFFF"           # Default text
command_echo_color = "#FFFFFF"   # Command echo

# Backgrounds
background_color = "#000000"     # Widget background
textarea_background = "-"        # Input background ("-" = transparent)

# Borders
border_color = "#00FFFF"         # Unfocused borders
focused_border_color = "#FFFF00" # Focused border

# Selection
selection_bg_color = "#4a4a4a"   # Text selection

Example: Dark Theme

[ui]
text_color = "#E0E0E0"
background_color = "#1A1A1A"
border_color = "#333333"
focused_border_color = "#007ACC"
selection_bg_color = "#264F78"

Example: Light Theme

[ui]
text_color = "#333333"
background_color = "#FFFFFF"
border_color = "#CCCCCC"
focused_border_color = "#0066CC"
selection_bg_color = "#ADD6FF"

Text Presets

Presets color semantic text types from the game:

Default Presets

[presets.speech]
fg = "#53a684"       # Player dialogue

[presets.monsterbold]
fg = "#a29900"       # Creature names

[presets.roomName]
fg = "#9BA2B2"
bg = "#395573"       # Room titles

[presets.links]
fg = "#477ab3"       # Clickable objects

[presets.whisper]
fg = "#60b4bf"       # Whispers

[presets.thought]
fg = "#FF8080"       # ESP/thoughts

Custom Preset

[presets.my_custom]
fg = "#FF6600"
bg = "#1A1A1A"

Prompt Colors

Color individual prompt characters:

[[prompt_colors]]
character = "R"         # Roundtime
color = "#FF0000"

[[prompt_colors]]
character = "S"         # Spell RT
color = "#FFFF00"

[[prompt_colors]]
character = "H"         # Hidden
color = "#9370DB"

[[prompt_colors]]
character = ">"         # Ready
color = "#A9A9A9"

Spell Colors

Color spell bars by spell number:

# Minor Spirit (500s)
[[spell_colors]]
spells = [503, 506, 507, 508, 509]
color = "#5c0000"

# Major Spirit (900s)
[[spell_colors]]
spells = [905, 911, 913]
color = "#9370db"

# Ranger (600s)
[[spell_colors]]
spells = [601, 602, 604, 605]
color = "#1c731c"

Color Palette

Define named colors for use in highlights:

[[color_palette]]
name = "danger"
color = "#FF0000"
category = "custom"

[[color_palette]]
name = "warning"
color = "#FFA500"
category = "custom"

[[color_palette]]
name = "success"
color = "#00FF00"
category = "custom"

Use in highlights:

[critical_hit]
pattern = "critical hit"
fg = "danger"      # Resolved from palette

Theme Design Tips

Color Harmony

Use complementary colors:

• Analogous: Colors next to each other on wheel
• Complementary: Opposite colors
• Triadic: Three evenly spaced colors

Contrast

Ensure readable text:

• Light text on dark background
• Dark text on light background
• Minimum 4.5:1 contrast ratio

Consistency

Use a limited color palette:

• 2-3 accent colors
• Neutral backgrounds
• Semantic colors (red=danger, green=success)

Complete Theme Examples

Nord Theme

[ui]
text_color = "#D8DEE9"
background_color = "#2E3440"
border_color = "#3B4252"
focused_border_color = "#88C0D0"
selection_bg_color = "#4C566A"

[presets.speech]
fg = "#A3BE8C"

[presets.monsterbold]
fg = "#D08770"

[presets.roomName]
fg = "#ECEFF4"
bg = "#434C5E"

[presets.links]
fg = "#81A1C1"

[presets.whisper]
fg = "#B48EAD"

[[prompt_colors]]
character = "R"
color = "#BF616A"

[[prompt_colors]]
character = ">"
color = "#616E88"

Solarized Dark

[ui]
text_color = "#839496"
background_color = "#002B36"
border_color = "#073642"
focused_border_color = "#2AA198"
selection_bg_color = "#073642"

[presets.speech]
fg = "#859900"

[presets.monsterbold]
fg = "#CB4B16"

[presets.roomName]
fg = "#93A1A1"
bg = "#073642"

[presets.links]
fg = "#268BD2"

[[prompt_colors]]
character = "R"
color = "#DC322F"

[[prompt_colors]]
character = ">"
color = "#586E75"

High Contrast

[ui]
text_color = "#FFFFFF"
background_color = "#000000"
border_color = "#FFFFFF"
focused_border_color = "#FFFF00"
selection_bg_color = "#0000FF"

[presets.speech]
fg = "#00FF00"

[presets.monsterbold]
fg = "#FF0000"

[presets.roomName]
fg = "#FFFFFF"
bg = "#0000AA"

[presets.links]
fg = "#00FFFF"

[[prompt_colors]]
character = "R"
color = "#FF0000"

[[prompt_colors]]
character = ">"
color = "#FFFFFF"

Monokai

[ui]
text_color = "#F8F8F2"
background_color = "#272822"
border_color = "#49483E"
focused_border_color = "#F92672"
selection_bg_color = "#49483E"

[presets.speech]
fg = "#A6E22E"

[presets.monsterbold]
fg = "#FD971F"

[presets.roomName]
fg = "#F8F8F2"
bg = "#3E3D32"

[presets.links]
fg = "#66D9EF"

[[prompt_colors]]
character = "R"
color = "#F92672"

[[prompt_colors]]
character = ">"
color = "#75715E"

Applying Themes

Hot-Reload

.reload colors

Per-Character

Place theme in character folder:

~/.two-face/characters/MyChar/colors.toml

Creating Variants

Dark/Light Toggle

Create two theme files:

~/.two-face/themes/dark.toml
~/.two-face/themes/light.toml

Switch by copying:

cp ~/.two-face/themes/dark.toml ~/.two-face/colors.toml

Profession Variants

Create profession-specific themes:

~/.two-face/characters/Warrior/colors.toml   # Combat colors
~/.two-face/characters/Empath/colors.toml    # Healing colors

Sharing Themes

1. Export your colors.toml
2. Share via GitHub Gist, Discord, etc.
3. Others copy to their ~/.two-face/ directory
4. Run .reload colors

See Also

• Colors Configuration - Full reference
• Theme System Architecture - How theming works
• Accessibility - High contrast themes

Highlight Patterns

Highlights let you colorize text based on patterns. This guide covers advanced pattern creation.

Pattern Basics

Highlights use regex (regular expressions):

[[highlights]]
name = "creatures"
pattern = "(?i)\\b(goblin|orc|troll)\\b"
fg = "#FF6600"
bold = true

Regex Syntax

Literal Text

# Exact match
pattern = "goblin"

# Multiple words
pattern = "goblin|orc|troll"

Character Classes

# Any digit
pattern = "\\d+"          # Matches: 123, 45, 6789

# Any word character
pattern = "\\w+"          # Matches: word, Word123

# Any whitespace
pattern = "\\s+"          # Matches spaces, tabs

# Custom class
pattern = "[A-Z][a-z]+"   # Matches: Hello, World

Quantifiers

# Zero or more
pattern = "a*"            # Matches: "", a, aa, aaa

# One or more
pattern = "a+"            # Matches: a, aa, aaa

# Zero or one
pattern = "colou?r"       # Matches: color, colour

# Exactly n
pattern = "\\d{3}"        # Matches: 123, 456

# n to m
pattern = "\\d{2,4}"      # Matches: 12, 123, 1234

Anchors

# Start of line
pattern = "^You attack"

# End of line
pattern = "falls dead!$"

# Word boundary
pattern = "\\bgoblin\\b"  # Won't match "goblins" or "hobgoblin"

Groups

# Non-capturing group
pattern = "(?:goblin|orc)"

# Capturing group (for future use)
pattern = "(\\w+) says,"

Modifiers

# Case insensitive
pattern = "(?i)goblin"    # Matches: goblin, Goblin, GOBLIN

Common Patterns

Creature Names

[[highlights]]
name = "creatures"
pattern = "(?i)\\b(goblin|orc|troll|kobold|giant|wolf|bear)s?\\b"
fg = "#FF6600"
bold = true

Player Speech

[[highlights]]
name = "speech"
pattern = "^(\\w+) (says|asks|exclaims|whispers),"
fg = "#00FF00"

Your Character Name

[[highlights]]
name = "my_name"
pattern = "\\bYourCharacterName\\b"
fg = "#FFFF00"
bold = true

Damage Numbers

[[highlights]]
name = "damage"
pattern = "\\b\\d+\\s+points?\\s+of\\s+damage"
fg = "#FF0000"
bold = true

Currency

[[highlights]]
name = "silver"
pattern = "\\d+\\s+silvers?"
fg = "#C0C0C0"

[[highlights]]
name = "gold"
pattern = "\\d+\\s+gold"
fg = "#FFD700"

Room Exits

[[highlights]]
name = "exits"
pattern = "Obvious (paths|exits):"
fg = "#00FFFF"

ESP/Thoughts

[[highlights]]
name = "esp"
pattern = "^\\[.*?\\]"
fg = "#FF00FF"
stream = "thoughts"

Critical Hits

[[highlights]]
name = "critical"
pattern = "(?i)critical|devastating|massive"
fg = "#FF0000"
bg = "#400000"
bold = true

Healing

[[highlights]]
name = "healing"
pattern = "heal|restore|recover"
fg = "#00FF00"

Stream Filtering

Limit patterns to specific streams:

[[highlights]]
name = "combat"
pattern = "You (hit|miss)"
fg = "#FF0000"
stream = "main"

[[highlights]]
name = "esp_highlight"
pattern = "\\[ESP\\]"
fg = "#00FFFF"
stream = "thoughts"

Priority System

Higher priority wins when multiple patterns match:

[[highlights]]
name = "important"
pattern = "critical"
fg = "#FF0000"
priority = 100          # Checked first

[[highlights]]
name = "general"
pattern = ".*"
fg = "#808080"
priority = 0            # Checked last

Fast Parse Mode

For simple literal patterns, use fast_parse:

[[highlights]]
name = "names"
pattern = "Bob|Alice|Charlie"
fg = "#FFFF00"
fast_parse = true       # Uses Aho-Corasick algorithm

When to use fast_parse:

• Pattern is literal strings only
• Pattern has many alternatives
• High-frequency matching needed

When NOT to use:

• Pattern uses regex features
• Pattern needs word boundaries
• Pattern uses anchors

Special Characters

Escape these with \\:

. * + ? ^ $ { } [ ] ( ) | \

# Match literal period
pattern = "Mr\\. Smith"

# Match literal asterisk
pattern = "\\*\\*emphasis\\*\\*"

# Match literal parentheses
pattern = "\\(optional\\)"

Sounds

Add sounds to highlights:

[[highlights]]
name = "whisper_alert"
pattern = "whispers to you"
fg = "#00FFFF"
sound = "~/.two-face/sounds/whisper.wav"

Squelch (Hide)

Hide matching text entirely:

[[highlights]]
name = "spam_filter"
pattern = "A gentle breeze|The sun|Birds chirp"
squelch = true

Redirect

Send matching text to different window:

[[highlights]]
name = "combat_redirect"
pattern = "You (attack|hit|miss|dodge)"
redirect = "combat"
redirect_mode = "copy"  # or "move"

Testing Patterns

Test in Browser

.highlights

Navigate to your highlight and check the preview.

Test with Game Output

1. Add highlight
2. Run .reload highlights
3. Trigger the pattern in-game
4. Verify appearance

Online Regex Testers

Use regex101.com or similar to test patterns before adding.

Performance Tips

1. Use fast_parse for simple patterns
2. Use word boundaries \b to limit matching
3. Be specific - avoid .* when possible
4. Limit stream - use stream = "main" when appropriate
5. Keep count low - fewer than 100 patterns recommended

Debugging

Pattern Not Matching

1. Test pattern in regex101.com
2. Check escaping (use \\ not \)
3. Check case sensitivity
4. Verify stream setting

Pattern Too Broad

Add boundaries:

# Too broad
pattern = "hit"        # Matches "white", "smith"

# Better
pattern = "\\bhit\\b"  # Only matches "hit" as word

Escaping Issues

TOML strings need double backslashes:

# Wrong
pattern = "\d+"

# Correct
pattern = "\\d+"

Complete Example

# Combat Highlights
[[highlights]]
name = "damage_taken"
pattern = "(?i)(strikes|hits|bites|claws|slashes)\\s+you"
fg = "#FF4444"
bold = true
priority = 80

[[highlights]]
name = "damage_dealt"
pattern = "You\\s+(strike|hit|slash|stab)"
fg = "#44FF44"
priority = 80

[[highlights]]
name = "critical"
pattern = "(?i)critical|devastating"
fg = "#FF0000"
bg = "#400000"
bold = true
priority = 100

# Creatures
[[highlights]]
name = "creatures"
pattern = "(?i)\\b(goblin|orc|troll|kobold|wolf|bear|rat)s?\\b"
fg = "#FF8800"
bold = true
priority = 50

# Social
[[highlights]]
name = "my_name"
pattern = "\\bYourCharacter\\b"
fg = "#FFFF00"
bold = true
priority = 90

[[highlights]]
name = "friends"
pattern = "\\b(Alice|Bob|Charlie)\\b"
fg = "#00FF00"
fast_parse = true
priority = 60

# Currency
[[highlights]]
name = "silver"
pattern = "\\d+\\s+silvers?"
fg = "#C0C0C0"
bold = true

[[highlights]]
name = "treasure"
pattern = "(?i)(gold|gems?|jewel|treasure)"
fg = "#FFD700"

See Also

• Highlights Configuration - Full reference
• Theme System - How colors work
• Performance - Optimization

Keybind Actions

Two-Face supports extensive keyboard customization. This guide covers all available keybind actions.

Keybind Basics

Keybinds are defined in keybinds.toml:

[keybinds."ctrl+l"]
action = "layout_editor"

[keybinds."f1"]
action = "help"

[keybinds."ctrl+1"]
macro = "attack target"

Key Format

Modifiers

Special Keys

Combination Examples

"ctrl+s"         # Ctrl + S
"ctrl+shift+s"   # Ctrl + Shift + S
"alt+f4"         # Alt + F4
"f1"             # F1 alone
"shift+tab"      # Shift + Tab

Action Categories

Navigation Actions

Window Actions

Editor Actions

Input Actions

Text Actions

Tab Actions

Application Actions

Game Actions

Macros

Send game commands:

[keybinds."ctrl+1"]
macro = "attack target"

[keybinds."ctrl+2"]
macro = "stance defensive"

[keybinds."ctrl+h"]
macro = "hide"

Multi-Command Macros

Separate with semicolons:

[keybinds."f5"]
macro = "stance offensive;attack target"

Macro with Variables

Use $input for prompted input:

[keybinds."ctrl+g"]
macro = "go $input"
# Prompts for input, then sends "go <input>"

Default Keybinds

Global

Navigation