Mastering Ratty: A Complete Guide to the Fun, GPU-Accelerated Terminal Emulator

Overview

If you've spent any time on Linux, you know there's no shortage of terminal emulators. Most of us stick with the default or have a favorite like Kitty or Alacritty. But every now and then, something comes along that makes you do a double-take. Ratty is that something. It's a modern, Rust-based terminal emulator that ditches the boring cursor in favor of a spinning 3D rat. Yes, a rat. But Ratty isn't just a gimmick—it's a fully functional, GPU-rendered emulator that can display 3D models inline, warp your terminal into a Mobius strip, and even show images. Built with the Bevy game engine and inspired by TempleOS’s retro aesthetic, Ratty proves that terminals can be both powerful and playful. This guide will walk you through everything you need to know: from installation to using its most eye-catching features.

Prerequisites

Before diving in, make sure your system meets these requirements:

• Operating System: Linux (Ratty is primarily developed for Linux; Windows/macOS support may be limited).
• Hardware: A GPU that supports Vulkan (for the Bevy engine). Most modern dedicated or integrated GPUs work fine.
• Software: Rust toolchain (if building from source), Git (to clone the repository), and standard build tools like build-essential or cmake.
• Knowledge: Basic familiarity with the command line and compiling Rust projects.

If you're not sure about your GPU, run glxinfo | grep OpenGL or install vulkan-tools and run vulkaninfo to verify Vulkan support.

Step-by-Step Guide

1. Installing Ratty

Ratty is available via source code on GitHub. You can also check if prebuilt binaries exist (the project is still experimental).

1. Open a terminal and clone the repository:

   git clone https://github.com/orhun/ratty.git
   cd ratty

2. Build Ratty using Cargo (this may take a few minutes):

   cargo build --release

3. After compilation, find the binary in target/release/ratty. You can copy it to a directory in your PATH (e.g., ~/.local/bin).
4. Launch Ratty by running ./ratty or just ratty if placed in PATH.

On first launch, you'll see a standard terminal with a spinning 3D rat as the cursor. Congratulations, you're in!

2. Basic Configuration

Ratty currently doesn't have a full config file, but many features are toggled via keyboard shortcuts. To customize the appearance, you can modify the source code or wait for future releases. For now, let's explore the built-in features.

3. Working with the 3D Cursor

The most obvious feature is the 3D rat cursor. By default, it rotates continuously. As you type, the rat moves with the text insertion point. To change the cursor model, you'd need to edit the source (look for assets folder), but the default rat is charming enough.

• The cursor is GPU-rendered, so performance is smooth even with complex shapes.
• You can disable the 3D cursor by pressing Ctrl+Alt+R (to revert to a standard block cursor). Press again to re-enable.

4. Entering 3D Mode

Ratty’s 3D Mode transforms the entire terminal into a canvas you can warp and view from any angle. To activate:

• Press Ctrl+Alt+Enter. The terminal window becomes part of a 3D scene. You can drag it around using the mouse (left-click and drag).
• Use Super+Ctrl+Alt+Up to increase warp (curve the terminal surface) and Super+Ctrl+Alt+Down to reduce warp.

For a truly mind-bending experience, try Mobius Mode:

• Press Ctrl+Alt+M. The terminal output twists into a continuous Mobius strip. This showcases Bevy engine's ability to deform geometry in real time.

5. Inline 3D Objects

Ratty supports anchoring 3D models directly to text cells. This means as you scroll, the 3D objects move with the text. To use this feature, you'll need to write a program that communicates via the Ratty Graphics Protocol (a custom protocol).

Example (conceptual):

// Pseudocode for sending a 3D model
ratty_graphics_send("model.glb", row=10, col=5);

The Ratty Graphics Protocol uses terminal escape sequences to tell the emulator where to place models. For now, only developers can create custom objects, but you can test inline models by running:

echo -e '\033_RattyGraphics\033\\'

(Check the project's README for exact sequences.)

6. Built-in Image Support

Ratty implements the Kitty Graphics Protocol, meaning you can display images directly in the terminal. To show an image:

kitty +kitten icat image.png

If you don't have the Kitty icat tool, you can use a simple script that sends the proper escape codes. Ratty renders images in the terminal area without external windows.

Common Mistakes

• Missing Vulkan drivers: Ratty requires libvulkan1 and vulkan-loader. Install them via your package manager (e.g., sudo apt install libvulkan1).
• Build errors: Ensure you have the latest Rust stable toolchain (rustup update stable). Also, some dependencies like libudev-dev may be needed on Debian/Ubuntu.
• 3D Mode not working: This could be due to lack of GPU acceleration. Run ratty from a terminal with RUST_LOG=debug to see error messages.
• Misunderstanding inline objects: The feature is experimental; you need to send correct escape sequences. Look at the project's examples folder for guidance.
• Expecting full configurability: Ratty is a fun experiment, not a daily driver. Don't expect features like tabs, split panes, or comprehensive settings.

Summary

Ratty is a delightful blend of terminal utility and game-engine flair. Its spinning rat cursor, 3D Mode, Mobius strip, inline 3D objects, and image support make it one of the most unique emulators out there. While it's not intended to replace your daily terminal, it's perfect for impressing friends, prototyping graphical terminal ideas, or just having fun. The installation is straightforward if you have Rust and Vulkan. Remember to check the official GitHub repo for updates and bug fixes. Give Ratty a try—you might never look at a boring block cursor the same way again.