Ratty: A GPU-rendered terminal emulator with inline 3D graphics

The problem Ratty solves, and who actually has it

A terminal is a grid of cells and a stream of bytes. That model has held for decades, and every emulator that matters implements roughly the same contract: parse escape sequences, keep a scrollback, hand keystrokes to a pty. Ratty keeps that contract and adds a second surface next to it. The README describes the project as a GPU-rendered terminal emulator with inline 3D graphics, inspired by TempleOS and built with Rust and Ratatui. The interesting word is inline. Objects are not drawn in a separate window that floats above the terminal; they are placed at terminal cell anchors, so a program can print text on one line and a rotating model on the next.

That makes Ratty a tool for a narrow audience. If you write TUI applications and you have ever wanted a diagram, a model preview or a spatial visualization inside the text interface itself, this is aimed at you. The repository ships a Ratatui widget called ratatui-rgp in the widget/ directory for exactly that purpose. If you only run git, ssh and a build, the 3D layer is decoration. The project is also explicit that it is a terminal emulator, not a library you bolt onto an existing one, so adopting it means changing the program you type into.

Bevy and wgpu underneath, ratty-vt for the terminal state

The dependency list in Cargo.toml tells most of the architecture story. Bevy 0.19 is pulled in with default features off and a hand-picked set that includes bevy_pbr, bevy_gltf, bevy_scene, bevy_sprite_render, bevy_text, bevy_winit and gltf_animation. That is a 3D renderer and a windowing layer, not a text stack. Text rendering goes through bevy_terminal_ratatui 0.7.3 with system_fonts enabled, and the terminal grid itself comes from ratty-vt, a path dependency in crates/ratty-vt with its own version number. Pty handling is portable-pty 0.8, so the shell you get is a real child process on a real pty.

Asset formats are handled by tobj for .obj and stl_io 0.11 for .stl, with glTF covered by Bevy's own loader. That matches the README's claim that cursor models and protocol assets can be .obj, .glb or .stl. Configuration is TOML through the toml crate, with shellexpand 3.1 for path expansion, which is why cursor.model.path can be a bare filename. The workspace has two members, the root package and crates/ratty-vt, and it excludes widget from the workspace, so ratatui-rgp builds on its own rather than as part of the emulator.

Installing Ratty and toggling 3D mode for the first time

The README lists one hard requirement before any install path: a GPU and graphics stack supported by Bevy and wgpu. Everything else is packaging. If you have a Rust toolchain, crates.io is the shortest route. The command below installs the published crate, and on success you get a ratty binary on your PATH.

cargo install ratty

On Arch the package is in extra, so pacman is faster than a source build. Nix users can run it straight from the flake without installing anything, and prebuilt binaries are on the GitHub releases page for direct download.

sudo pacman -S ratty

nix run github:orhun/ratty

Building from Git needs system libraries beyond the Rust toolchain. The README gives the package names per distribution: gcc, pkgconf, libfontconfig-dev and libwayland-dev on Debian and Ubuntu; gcc, fontconfig-devel and wayland-devel on Fedora; and on Bazzite or Bluefin the same three through rpm-ostree followed by a reboot.

cargo install --git https://github.com/orhun/ratty

Once it launches, the first thing worth doing is pressing Ctrl+Alt+Enter. The README says this toggles between 2D and orthographic 3D, and it is the fastest way to confirm the GPU path is working rather than falling back to something flat. From there Ctrl+Alt+P toggles perspective and Ctrl+Alt+M toggles Mobius mode. Camera slots are bound to Ctrl+Alt+Shift+0 through Ctrl+Alt+Shift+9; the extra Shift modifier exists so that slot 0 does not collide with Ctrl+Alt+0, which resets the font size. Font size itself is Ctrl+= and Ctrl+-, with Ctrl+Alt+0 as the reset.

Configuring the cursor model in ratty.toml

The default configuration lives at config/ratty.toml in the repository, and the README says to copy it to $HOME/.config/ratty/ratty.toml before editing. The cursor is a 3D model rather than a block, and the shipped example is a spinning rat. The relevant keys are split into a model table and an animation table.

[cursor.model]
path = "CairoSpinyMouse.obj"
scale_factor = 6.0
brightness = 0.5
x_offset = 0.5
plane_offset = 18.0
visible = true

[cursor.animation]
spin_speed = 1.4
bob_speed = 2.2
bob_amplitude = 0.08

Each field has a documented job. scale_factor sizes the model relative to a terminal cell, brightness adjusts the material, x_offset shifts it horizontally inside the cell, and plane_offset pushes it away from the warped terminal surface when 3D mode is on. visible decides whether you see the custom model at all or only the plain terminal cursor. The animation table controls spin and a vertical bob. If you set visible to false you keep the rest of the 3D rendering and lose the rat, which is a reasonable first edit if the model distracts you while reading output.

The Ratty Graphics Protocol and what it does not cover

Inline objects are not done with a general-purpose escape sequence. Ratty defines its own, documented in protocols/graphics.md as the Ratty Graphics Protocol, or RGP. According to the README, RGP supports registering .obj, .glb and .stl assets by path, placing them at terminal cell anchors, and setting animation, scale, color and depth attributes. It also carries camera control, which is how a program can switch a placed object between flat, orthographic, perspective and Mobius views. The widget/examples/big_rat.rs demo does exactly this: it places one oversized rat and cycles the camera with the v key.

This is the part of the project with the sharpest trade-off. A program that uses RGP renders 3D correctly in Ratty and nowhere else, because no other terminal implements the protocol. The README does note image support through the Kitty Graphics Protocol, so ordinary image display has a path that other terminals share, but the 3D placement layer does not. There is no fallback described for a terminal that lacks RGP, which means a TUI that leans on inline objects either detects Ratty or degrades to plain text on its own. The README does not document an RGP capability query, so a portable application has to decide for itself how to find out.

Where Ratty is the wrong tool

The requirement list is the first boundary. Ratty needs a GPU and a graphics stack that Bevy and wgpu support. A headless server, a VM without GPU passthrough, or a remote session where you only have a text channel is not a target for this, and the README does not present a software-rendering fallback. Even on a workstation, the practical question is whether Bevy initializes on your driver. That is a dependency of a dependency, and it is worth checking before you spend time on configuration.

Memory and startup cost follow from the same choice. Bevy with bevy_pbr, bevy_gltf and the sprite renderer is a full 3D engine, and it is linked into a program whose primary job is to display characters. The README does not publish startup times or memory figures, so treat the cost as unquantified rather than small. The second boundary is portability of your own work. If you build a TUI on ratatui-rgp, the 3D parts are Ratty-only, and the widget lives outside the Cargo workspace, so it has its own release cadence. The third is the obvious one: the 3D modes are a feature you will use occasionally. If you want a terminal that is fast, boring and identical on every machine you log into, the 3D layer is weight you carry for nothing.

How Ratty differs from a conventional GPU terminal

The nearest comparison is a GPU-accelerated terminal such as Alacritty or Kitty. Those projects also move text rendering onto the GPU, and Kitty defines its own graphics protocol for images. The difference is what the GPU is for. In Alacritty the GPU exists to draw glyphs quickly and to keep latency low; there is no scene graph, no camera and no asset pipeline. Kitty's graphics protocol places raster images in the grid, which is a two-dimensional problem with a well-understood answer.

Ratty keeps the same text path but adds a 3D scene on top of it, using Bevy as the renderer and glTF, OBJ and STL as the asset formats. That is a different category of feature. Placing a perspective-projected model at a cell anchor, with depth and animation attributes and a switchable camera, is not something an image protocol does. The cost is the dependency surface: Bevy and wgpu instead of a lean glyph renderer. So the choice is not which terminal renders text faster, because the README makes no performance claim either way. It is whether you want a scene graph in your terminal badly enough to accept a 3D engine in the binary.

Licence, release cadence and upgrade cost

Ratty is MIT licensed, both in the repository's LICENSE file and in the license field of Cargo.toml. MIT is permissive: it allows use, modification and redistribution provided the copyright notice and permission notice are kept, and it comes with no warranty. That matters here because the project embeds assets, including a default cursor model, and links Bevy, which is also permissively licensed. If you redistribute a binary, keep the notices intact. This is a description of the licence text, not legal advice; read LICENSE yourself if the distinction matters to your organization.

The repository is not archived, and the last push was on 2026-09-22. Recent releases are v0.5.0 on 2026-07-05, v0.4.2 on 2026-06-15 and v0.4.1 on 2026-05-30, and the root package version in Cargo.toml is 0.5.0. The version number is still below 1.0, so configuration keys and protocol details can move. The README already shows one such move: Toggle3DMode is kept as a backward-compatible alias for ToggleOrtho3DMode in custom configs, which tells you the action names are not frozen. Upgrading also means tracking Bevy, since the manifest pins 0.19.0 and a Bevy major bump can change the feature set Ratty enables. Budget for reading CHANGELOG.md on each release rather than assuming your ratty.toml keeps working.

Editorial conclusion

Adopt Ratty if you want a working terminal that also renders 3D assets inline, and you are willing to build against the Ratty Graphics Protocol to get that. Do not adopt it as the terminal you run over SSH on a headless box, or on hardware where Bevy and wgpu have no supported graphics stack, because the README lists that stack as a requirement. Verify two things before you commit: that your GPU and driver combination is one Bevy and wgpu support, and that the assets you want to place are .obj, .glb or .stl, since those are the three formats the protocol registers.

Frequently asked questions

Official sources

1. License: MIT
2. orhun/ratty on GitHub
3. Project website
4. README
5. Releases