#roguelike #gamedev #terminal #ascii #cp437


ASCII/Codepage 437 terminal emulator with a game loop. Defaults to OpenGL, also support WebGPU (for Vulkan/Metal/WGPU), Curses and Crossterm for output. Part of the bracket-lib family.

8 releases

0.8.7 Oct 4, 2022
0.8.5 Jul 6, 2021
0.8.2 Feb 15, 2021
0.8.1 Apr 29, 2020
0.1.0 Feb 21, 2020

#682 in Game dev

Download history 554/week @ 2023-06-05 482/week @ 2023-06-12 1630/week @ 2023-06-19 1072/week @ 2023-06-26 889/week @ 2023-07-03 1009/week @ 2023-07-10 1225/week @ 2023-07-17 1207/week @ 2023-07-24 587/week @ 2023-07-31 1303/week @ 2023-08-07 1492/week @ 2023-08-14 532/week @ 2023-08-21 753/week @ 2023-08-28 1352/week @ 2023-09-04 759/week @ 2023-09-11 973/week @ 2023-09-18

3,884 downloads per month
Used in 5 crates (2 directly)

MIT license

18K SLoC


bracket-terminal is part of the bracket-lib family. It provides a virtual ASCII/Codepage-437 terminal (with optional tile graphic support and layers), and a game loop. This frees you up from implementation difficulties, making it easy to write grid-based games (Roguelikes are a great fit, but any grid/tile-based game can work). It also provides assistance with keyboard and mouse input.

Bracket-terminal supports multiple back-ends:

  • The default is OpenGL, which works on just about everything. The GL back-end supports all features, including post-processing (retro screen effects) and layers.
  • The WebGL (WASM) back-end works in Web Assembly, allowing you to compile your bracket-terminal-based game for the web.
  • The webgpu back-ends provide rendering in Vulkan, Metal, and WebGPU. It currently supports everything except the post-processing effects.
  • The crossterm back-end runs natively in your existing terminal. Graphical features are not supported.
  • The curses back-end runs natively in *NIX terminals, or in a pdcurses terminal emulator on Windows. Graphical features are not supported.

BREAKING CHANGE ALERT: The crossterm feature is now cross_term if you are using bracket-terminal directly. It's still crossterm for bracket-lib and rltk.

IMPORTANT: If you are running the webgpu backend, you need to add resolver = 2 to your Cargo.toml file. WGPU requires it for platform selection.

Why bracket-terminal and not direct console rendering?

Bracket-terminal can do terminal rendering, but if that is your only target you may be better off using crossterm. Bracket-terminal gets you a few features you don't find elsewhere:

  • It is game-loop based, so it is ideal for frame-oriented game programming.
  • Codepage-437 emulation is sprite-based on graphical back-ends. You can be absolutely sure that your game will look the same on all platforms, using exactly the font(s) you specify.
  • It provides multiple layers, which can use different font/sprite files.
  • There are some retro post-processing effects available if you like them.
  • bracket-terminal works hard to be simple and straightforward, making for a great learning environment.

Minimal example

The following code is enough to put Hello Minimal Bracket World on the screen:

use bracket_terminal::prelude::*;

struct State {}

impl GameState for State {
    fn tick(&mut self, ctx: &mut BTerm) {
        ctx.print(1, 1, "Hello Bracket World");

fn main() -> BError {
    let context = BTermBuilder::simple80x50()
        .with_title("Hello Minimal Bracket World")

    let gs: State = State {};
    main_loop(context, gs)

It's worth noting that (0,0) in bracket-terminal is the top-left of the screen.


Run an example with cargo run --example <name>.

  • hello_minimal puts "Hello Minimal Bracket World" on the screen. Try it with WASM
  • hello_terminal puts a bouncing "Hello World" on the screen in color, with frames-per-second [FPS] counting, and frame-rate limiting. Try it with WASM
  • sparse is the same demo, but with a second layer in a VGA 8x16 font on a second layer, no frame-rate limiting, and utilizing batched command submission. Try it with WASM
  • walking lets you use your keyboard to walk an @ symbol around a random map. Try it with WASM
  • astar-mouse lets you use your mouse to move around a random map, using A-Star pathing (from the bracket-pathfinding crate) to avoid obstacles. Try it with WASM
  • tiles is similar to the walking demo, but uses two layers of graphical tiles (graphical back-ends only). Try it with WASM
  • rex demonstrates loading a sprite from REX Paint and rendering it to the terminal. Try it with WASM
  • postprocess demonstrates the library's post-processing effects - scan lines and screen burn. Try it with WASM
  • textblock demonstrates the TextBlock system, giving you a "builder" approach to constructing larger blocks of text with word-wrapping and formatting. Try it with WASM
  • dwarfmap demonstrates using the terminal with Algorithm3D to provide a Dwarf Fortress style 3D map (2D "slices" of a 3D world). It uses the bracket-noise library for terrain generation. Try it with WASM
  • keyboard demonstrates keyboard scan-code input. It's mostly useful for debugging. Try it with WASM
  • textsprites demonstrates multi-tile sprites. Try it with WASM
  • native_gl shows you how to access OpenGL directly. Only works with opengl back-ends, WASM or native. Try it with WASM

Running the examples with other back-ends

You can run the dwarfmap example with different back-ends like this. The same principle applies to other back-ends:

  • OpenGL : cargo run --example dwarfmap
  • WGPU: cargo run --example dwarfmap --no-default-features --features "webgpu"
  • Curses: cargo run --example dwarfmap --no-default-features --features "curses"
  • Crossterm: (note that the feature is called cross_term) cargo run --example dwarfmap --no-default-features --features "cross_term"


~268K SLoC