ratty

Ratty: A GPU-rendered terminal emulator with inline 3D graphics
Inspired by TempleOS | Built with Rust & Ratatui

["Rodent-obsessed developer creates Ratty to bring 3D graphics to the command line"](https://www.theregister.com/software/2026/05/11/ratty-terminal-emulator-brings-3d-graphics-to-the-command-line/5238299) - The Register ["This New Terminal is Absurd (But Totally Fun)"](https://itsfoss.com/ratty-terminal/) - It's FOSS ["10 weird OSS projects you need right now... "](https://www.youtube.com/watch?v=qPuzWFvRajk) - Fireship ["Your terminal can render in 3D now, and Rust made it surprisingly usable"](https://www.makeuseof.com/terminal-render-3d-rust-made-surprisingly-usable/) - MakeUseOf ## Features - Spinning rat cursor ([customizable](#changing-the-cursor)) - Traditional 2D and [new 3D mode](#3d-mode)! - [Inline 3D objects](#inline-3d-objects) - [GPU-backed text rendering](#rendering-pipeline) - Image support (via Kitty Graphics Protocol >:\() ▶️ [Watch the demo video here!](https://youtu.be/cY9AX5j-osY) [Read the behind the scenes blog post here!](https://blog.orhun.dev/introducing-ratty) ### 3D mode Ever wondered what's _behind_ the terminal? Press Ctrl+Alt+Enter! ## Installation Requirements: - A GPU / graphics stack supported by Bevy and wgpu - Melted cheese (optional but recommended) ### [crates.io](https://crates.io/crates/ratty) ```bash cargo install ratty ``` ### [Arch Linux](https://archlinux.org/packages/extra/x86_64/ratty/) ```bash sudo pacman -S ratty ``` ### [Nix](nix/README.md) See the [Nix packaging docs](nix/README.md) for flake, NixOS, and Home Manager usage. ```bash nix run github:orhun/ratty ``` ### Binary releases Prebuilt binaries are available on the [GitHub releases page](https://github.com/orhun/ratty/releases) for direct download. ### From Git Requirements: - Rust toolchain with Cargo - on Bazzite / Bluefin: `sudo rpm-ostree install gcc fontconfig-devel wayland-devel` (then reboot) - on Debian / Ubuntu: `sudo apt-get update ; sudo apt-get install gcc pkgconf libfontconfig-dev libwayland-dev` - on Fedora: `sudo dnf install gcc fontconfig-devel wayland-devel` ```bash cargo install --git https://github.com/orhun/ratty ``` ## Configuration The default configuration file is available in [`config/ratty.toml`](config/ratty.toml). You can copy this file to `$HOME/.config/ratty/ratty.toml` and customize it. ### Changing the cursor ```toml [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 ``` For [`cursor.model.path`](config/ratty.toml), Ratty supports both `.obj`, `.glb`, and `.stl` assets. Other useful cursor fields are: - `scale_factor`: scales the model relative to the terminal cell size - `brightness`: adjusts the cursor material brightness - `x_offset`: shifts the cursor model horizontally inside the cell - `plane_offset`: pushes the cursor away from the warped terminal surface in 3D mode - `visible`: show the custom 3D cursor model instead of only the terminal cursor ## Key Bindings | Key | Action | | -------------------------------------------------------------- | -------------------- | | Ctrl+Shift+C | Copy selection | | Ctrl+Shift+V | Paste clipboard | | Ctrl+Alt+Enter | Toggle 2D / ortho 3D | | Ctrl+Alt+P | Toggle perspective | | Ctrl+Alt+M | Toggle Mobius mode | | Ctrl+Alt+Shift+0-9 | Activate camera slot | | Ctrl+Alt+Up | Increase warp | | Ctrl+Alt+Down | Decrease warp | | Alt+PageUp | Scroll one page up | | Alt+PageDown | Scroll one page down | | Alt+Up | Scroll one line up | | Alt+Down | Scroll one line down | | Ctrl+= | Increase font size | | Ctrl+- | Decrease font size | | Ctrl+Alt+0 | Reset font size | In custom configs, `ToggleOrtho3DMode` is the current action name for the orthographic 3D toggle. The old `Toggle3DMode` action remains supported as a backward-compatible alias. Camera slot actions are named `ActivateCameraSlot0` through `ActivateCameraSlot9`. The extra Shift modifier keeps slot 0 distinct from the existing Ctrl+Alt+0 font reset. ## Inline 3D objects Ratty uses its own protocol, the [Ratty Graphics Protocol](protocols/graphics.md), to place inline 3D objects in terminal space. RGP supports: - registering `.obj`, `.glb`, and `.stl` assets by path - placing them at terminal cell anchors - animation, scale, color, depth and other attributes - camera control for flat, orthographic, perspective and Mobius views There is a Ratatui widget called `ratatui-rgp` available in [`widget/`](widget/) if you want to build your own terminal applications that involve inline 3D objects. ### Examples #### [Big rat](widget/examples/big_rat.rs) Places a single oversized rat directly in your terminal. Press `v` in the demo to cycle the Ratty camera protocol through flat, orthographic, perspective and Mobius views. #### [Document](widget/examples/document.rs) TempleOS-inspired document demo with editable text and embedded inline 3D objects: #### [Draw](widget/examples/draw.rs) Split-pane drawing demo with a 2D canvas on the left and a live 3D preview on the right: #### [Rubik's cube](widget/examples/rubiks_cube.rs) Interactive 3D Rubik's cube demo: #### [Mobius Chess](widget/examples/mobius_chess.rs) A Mobius-strip chess demo: ### Apps Here are some applications explicitly built around Ratty's Graphics Protocol: #### [Ratscad](https://github.com/qewer33/ratscad) Terminal CAD: #### [Ratty-runner](https://github.com/ozzyocak/ratty-runner) Endless runner built for Ratty: #### [ComChan](https://github.com/Vaishnav-Sabari-Girish/ComChan) A blazingly fast serial monitor with plotter TUI and 3D telemetry ## Architecture ### Rendering pipeline The terminal surface currently uses [`ratatui`](https://github.com/ratatui/ratatui) for the UI buffer, [`bevy_terminal_ratatui`](https://github.com/gold-silver-copper/bevy_terminal) for text shaping/rendering and [Bevy](https://bevyengine.org/) for scene presentation. Current workflow: 1. PTY output is parsed by the [`ratty-vt` workspace crate](crates/ratty-vt/README.md) (Ratty's fork of [`vt100`](https://github.com/doy/vt100-rust)) and drawn into a Ratatui buffer on CPU 2. `bevy_terminal_ratatui` translates Ratatui's changed cells into a retained terminal surface 3. `bevy_terminal` shapes text with Bevy's font system and incrementally builds compact background, decoration, cursor, and glyph quads 4. Bevy's render world draws those quads into a renderer-owned `Rgba8UnormSrgb` texture 5. Ratty presents that stable texture handle in its flat, plane, perspective, and Mobius scenes The terminal image is fully GPU-resident: the only data crossing from the main world to the render world each frame is compact scene data, not pixels. ### Workspace development The Cargo workspace contains the Ratty application and the independent [`ratty-vt`](crates/ratty-vt/README.md) terminal engine. The widget remains a separate package under `widget/` with its own lockfile. ```sh cargo test -p ratty-vt --locked # Engine tests without building Bevy cargo test --workspace --locked # Application, engine, and doctests cargo package --workspace --locked # Verify both packages together ``` Ratty uses a local path dependency during development and a versioned `ratty-vt` dependency when published. See the engine's [publishing instructions](crates/ratty-vt/README.md#publishing) for release order. ## Touchscreen In 3D mode, drag with one finger to rotate the terminal. Move two fingers together to pan, and pinch them to zoom. Swipe diagonally from the bottom-left toward the top-right to enter Mobius mode. ## Endorsements - _"This is like a legitimately cool project but also I just spent like 20 minutes adjusting the config for the rat spinning to see him spin faster and more erratically and it cracked me up"_ - [@vimlena.com](https://bsky.app/profile/vimlena.com/post/3mkoshbzpvs2y) - _"These kinds of experiments are where creativity is born."_ - [@Coko7](https://github.com/Coko7) - _"No comments. Just support."_ - [@Raphamorim](https://github.com/raphamorim/) (creator of Rio terminal) - _"[tetro-tui](https://github.com/Strophox/tetro-tui) running in Ratty"_ - [@Strophox](https://github.com/Strophox) ## License All code is licensed under The MIT License. ノ( º \_ º ノ) - respect crables! ## Credits Ratty logo designed by [@Strophox](https://github.com/Strophox) & [@Harunocaksiz](https://github.com/harunocaksiz) ## Copyright Copyright © 2026, [Orhun Parmaksız](mailto:[email protected]) The author does not have a rat under the hat!