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.