Two-Face

A modern, feature-rich terminal client for GemStone IV.

Features

• Customizable Widget System - Progress bars, countdowns, compass, hands, indicators, injury doll, active effects, and more
• Tabbed Text Windows - Route game streams to organized tabs (thoughts, combat, loot, etc.)
• Highlight System - Regex-based text highlighting with Aho-Corasick fast matching
• Sound Alerts - Play sounds on pattern matches with volume control
• Direct eAccess Authentication - Connect directly to GemStone IV without Lich proxy
• Fully Themeable - Complete color customization with preset themes
• Layout Editor - Interactive widget positioning and resizing (F2)
• Comprehensive Testing - 1,003 tests including end-to-end UI integration tests

Quick Start

Via Lich Proxy (Recommended)

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

Direct Connection (Standalone)

two-face --direct \
  --account YOUR_ACCOUNT \
  --password YOUR_PASSWORD \
  --game prime \
  --character CHARACTER_NAME

Installation

Pre-built Binaries

Download from Releases.

Build from Source

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

# Build release binary
cargo build --release

# Binary is at target/release/two-face.exe

Requirements:

• Rust 1.70+ (stable)
• OpenSSL (for direct mode) - install via vcpkg on Windows

Documentation

Full Documentation - Comprehensive guides, tutorials, and reference

Quick links:

• Getting Started
• Configuration Guide
• Widget Reference
• Keybind Actions
• Troubleshooting

Default Keybinds

Key	Action
F2	Toggle layout editor
F3	Toggle highlight browser
Page Up/Down	Scroll main window
Tab	Cycle focus between widgets
Ctrl+C	Copy selected text
Escape	Close popups / cancel

See Keybind Reference for complete list.

Configuration

Two-Face uses TOML configuration files stored in ~/.two-face/:

~/.two-face/
├── config.toml        # Main configuration
├── layout.toml        # Widget layout
├── keybinds.toml      # Key bindings
├── highlights.toml    # Text highlighting rules
└── colors.toml        # Theme colors

Example highlight:

[[highlights]]
pattern = "You are stunned"
fg = "bright_red"
bold = true
sound = "alert.wav"

Architecture

┌─────────────────────────────────────────────────────────┐
│                      Network Layer                       │
│            (Lich Proxy / Direct eAccess)                │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│                    Parser (XML)                          │
│              Stormfront Protocol Handler                 │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│                  Core (AppCore)                          │
│         State Management & Message Processing            │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│                 TUI Frontend (Ratatui)                   │
│              Widget Rendering & Input                    │
└─────────────────────────────────────────────────────────┘

Contributing

Contributions welcome! Please see Contributing Guide.

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- --port 8000

License

Licensed under either of:

• MIT License (LICENSE-MIT)
• Apache License, Version 2.0 (LICENSE-APACHE)

at your option.

Acknowledgments

• Forked from VellumFE
• Built with Ratatui for terminal UI
• Inspired by Profanity