ruscii

An easy library to make terminal applications and games in rust.

The aim of this project is to make easier the game development in terminals. Any contribution, issue, or pull request would be welcome!

Features

• Optimized to render fast in terminals.
• Multi-platform (Linux, Windows and MacOS)
  • For linux, it is required to have a x11 server (most of distribution comes with it). Internally ruscii use it to create transparent key pressed and released events.
• Multi-terminal (See crossterm terminal support)
• Enable key press and release events in terminal (essential for games!).
• Easy to use. Make your terminal game in a few lines!
• Easy way to recover the terminal state at error.

Dependencies

To compile ruscii in linux, you need to have installed the X11 development libraries.

• In Ubuntu/Debian:

  sudo apt install libx11-dev
  

• In Fedora/RHEL/CentOS:

  sudo dnf install xorg-x11-server-devel
  

Windows and MacOS do not need any special dependency.

Examples

You can found several examples into the example folder.

To test an example, install ruscii with the examples flag and run it.

cargo install ruscii --examples
~/.cargo/bin/<example_name>

Or clone the repo and run the example:

cargo run --example <example_name> --release

Some of these examples:

Space invaders (200 lines):

Pong (150 lines):

Note: the first asciimedia playback could be shown laggy, a second playback fix this issue.

Projects using ruscii:

• thrust: A simple space shooter game. Runs in the terminal using characters-based UI.
• terminal-tetris: 🕹️ Tetris in the terminal written in Rust

If you have a project using ruscii and you want it to appear here. Open an issue!

Getting started

Test it in your own terminal!

Add the following line to your dependencies section in Cargo.toml file:

ruscii = "0.3"

Copy the following code in your main.rs to run the base ruscii application:

use ruscii::app::{App, State};
use ruscii::terminal::{Window};
use ruscii::drawing::{Pencil};
use ruscii::keyboard::{KeyEvent, Key};
use ruscii::spatial::{Vec2};
use ruscii::gui::{FPSCounter};

fn main() {
    let mut fps_counter = FPSCounter::new();
    let mut app = App::new();

    app.run(|app_state: &mut State, window: &mut Window| {
        for key_event in app_state.keyboard().last_key_events() {
            match key_event {
                KeyEvent::Pressed(Key::Esc) => app_state.stop(),
                KeyEvent::Pressed(Key::Q) => app_state.stop(),
                _ => (),
            }
        }

        fps_counter.update();

        let mut pencil = Pencil::new(window.canvas_mut());
        pencil.draw_text(&format!("FPS: {}", fps_counter.count()), Vec2::xy(1, 1));
    });
}

Debugging

Debug a terminal app is usually difficult because the app output and the backtrace goes to the same terminal view. Ruscii uses the standard output to render data and the standard error to log error information. We recommend to redirect the standard error to a file that can be inspected later.

For example, in bash it will be:

$ export RUST_BACKTRACE=1
$ cargo run 2> my_stderr