Struct console_engine::ConsoleEngine

pub struct ConsoleEngine {
    pub frame_count: usize,
    // some fields omitted
}

Console Engine Framework

Features

note : each link will redirect you to a bunch of functions

• Build custom terminal display using shapes or text
• Terminal handling with a target frame per seconds
• Keyboard and mouse support
• Terminal resizing support

Basic Usage:

use console_engine::pixel;
use console_engine::Color;
use console_engine::KeyCode;

fn main() {
    // initializes a screen of 20x10 characters with a target of 3 frame per second
    // coordinates will range from [0,0] to [19,9]
    let mut engine = console_engine::ConsoleEngine::init(20, 10, 3);
    let value = 14;
    // main loop, be aware that you'll have to break it because ctrl+C is captured
    loop {
        engine.wait_frame(); // wait for next frame + capture inputs
        engine.clear_screen(); // reset the screen

        engine.line(0, 0, 19, 9, pixel::pxl('#')); // draw a line of '#' from [0,0] to [19,9]
        engine.print(0, 4, format!("Result: {}", value).as_str()); // prints some value at [0,4]

        engine.set_pxl(4, 0, pixel::pxl_fg('O', Color::Cyan)); // write a majestic cyan 'O' at [4,0]

        if engine.is_key_pressed(KeyCode::Char('q')) { // if the user presses 'q' :
            break; // exits app
        }

        engine.draw(); // draw the screen
    }
}

Fields

frame_count: usize

The current frame count, publicly accessible Has no purpose internally, use it as you want

Implementations

impl ConsoleEngine

pub fn init(
    width: u32,
    height: u32,
    target_fps: u32
) -> Result<ConsoleEngine, ErrorKind>

Initialize a screen of the provided width and height, and load the target FPS

pub fn init_fill(target_fps: u32) -> Result<ConsoleEngine, ErrorKind>

Initialize a screen filling the entire terminal with the target FPS

pub fn init_fill_require(
    width: u32,
    height: u32,
    target_fps: u32
) -> Result<ConsoleEngine, ErrorKind>

Initialize a screen filling the entire terminal with the target FPS Also check the terminal width and height and assert if the terminal has at least the asked size

pub fn set_title(&mut self, title: &str)

Set the terminal’s title

pub fn get_width(&self) -> u32

Get the screen width

pub fn get_height(&self) -> u32

Get the screen height

pub fn clear_screen(&mut self)

Reset the screen to a blank state

pub fn fill(&mut self, pixel: Pixel)

Fill the entire screen to the given pixel

pub fn print(&mut self, x: i32, y: i32, string: &str)

prints a string at the specified coordinates. The string will be cropped if it reach the right border

usage:

engine.print(0,0, "Hello, world!");
engine.print(0, 4, format!("Score: {}", score).as_str());

pub fn print_fbg(&mut self, x: i32, y: i32, string: &str, fg: Color, bg: Color)

prints a string at the specified coordinates with the specified foreground and background color The string will automatically overlaps if it reach the right border

usage:

use console_engine::Color;

// print "Hello, world" in blue on white background
engine.print(0,0, "Hello, world!", Color::Blue, Color::White);

pub fn print_screen(&mut self, x: i32, y: i32, source: &Screen)

Prints another screen on specified coordinates. Useful when you want to manage several “subscreen”

see example screen-embed

usage:

use console_engine::pixel;
use console_engine::screen::Screen;

// create a new Screen struct and draw a square inside it
let mut my_square = Screen::new(8,8);
my_square.rect(0,0,7,7,pixel::pxl('#'));
my_square.print(1,1,"square");

// prints the square in the engine's screen at a specific location
engine.print_screen(5,2, &my_square);

pub fn print_screen_alpha(
    &mut self,
    x: i32,
    y: i32,
    source: &Screen,
    alpha_character: char
)

Prints another screen on specified coordinates, ignoring a specific character while printing Ignoring a character will behave like transparency

see print_screen for usage

pub fn line(
    &mut self,
    start_x: i32,
    start_y: i32,
    end_x: i32,
    end_y: i32,
    character: Pixel
)

draws a line of the provided character between two sets of coordinates see: Bresenham’s line algorithm

Note : Your line can start or end out of bounds. These pixels won’t be drawn

usage:

use console_engine::pixel;
// ...
engine.line(0, 0, 9, 9, pixel::pxl('#'));

pub fn rect(
    &mut self,
    start_x: i32,
    start_y: i32,
    end_x: i32,
    end_y: i32,
    character: Pixel
)

Draws a rectangle of the provided character between two sets of coordinates

usage:

use console_engine::pixel;
// ...
engine.rect(0, 0, 9, 9, pixel::pxl('#'));

pub fn rect_border(
    &mut self,
    start_x: i32,
    start_y: i32,
    end_x: i32,
    end_y: i32,
    rect_style: BorderStyle
)

Draws a rectangle with custom borders of the provided between two sets of coordinates. Check the BorderStyle struct to learn how to use built-in or custom styles

usage:

use console_engine::rect_style::BorderStyle;
// ...
engine.rect_border(0, 0, 9, 9, BorderStyle::new_simple());

pub fn fill_rect(
    &mut self,
    start_x: i32,
    start_y: i32,
    end_x: i32,
    end_y: i32,
    character: Pixel
)

Fill a rectangle of the provided character between two sets of coordinates

usage:

use console_engine::pixel;
// ...
engine.fill_rect(0, 0, 9, 9, pixel::pxl('#'));

pub fn circle(&mut self, x: i32, y: i32, radius: u32, character: Pixel)

Draws a circle of the provided character at an x and y position with a radius see: olcPixelGameEngine Repository

usage:

use console_engine::pixel;
// ...
engine.circle(10, 10, 4, pixel::pxl('#'));

pub fn fill_circle(&mut self, x: i32, y: i32, radius: u32, character: Pixel)

Fill a circle of the provided character at an x and y position with a radius see: olcPixelGameEngine Repository

usage:

use console_engine::pixel;
// ...
engine.fill_circle(10, 10, 4, pixel::pxl('#'));

pub fn triangle(
    &mut self,
    x1: i32,
    y1: i32,
    x2: i32,
    y2: i32,
    x3: i32,
    y3: i32,
    character: Pixel
)

Draws a triangle of the provided character using three sets of coordinates

usage:

use console_engine::pixel;
// ...
engine.triangle(8,8, 4,6, 9,2, pixel::pxl('#'));

pub fn fill_triangle(
    &mut self,
    x1: i32,
    y1: i32,
    x2: i32,
    y2: i32,
    x3: i32,
    y3: i32,
    character: Pixel
)

Fill a triangle of the provided character using three sets of coordinates see: rustyPixelGameEngine Repository

usage:

use console_engine::pixel;
// ...
engine.fill_triangle(8,8, 4,6, 9,2, pixel::pxl('#'));

pub fn scroll(&mut self, h_scroll: i32, v_scroll: i32, background: Pixel)

Scrolls the screen for a certain amount of characters vertically or horizontally Scrolling is a destructive process, the outer border will be filled with the background pixel.

Scrolling a positive value will move the screen characters to the left / top, freeing space to the right / bottom

Scrolling a negative value will move the screen characters to the right / bottom, freeing space to the left / top

usage :

use console_engine::pixel;

// fill the screen with characters
engine.fill(pixel::pxl('#'));
// free one space to the bottom
engine.scroll(0,1,pixel::pxl(' '));
// print something at this place
engine.print(0, height-1, "Hello, world!");

pub fn set_pxl(&mut self, x: i32, y: i32, character: Pixel)

sets the provided character in the specified coordinates out of bounds pixels will be ignored

usage:

use console_engine::pixel;
// ...
engine.set_pxl(3,8,pixel::pixel('o'));

pub fn get_pxl(&self, x: i32, y: i32) -> Result<Pixel, String>

Get the character stored at provided coordinates

usage:

if engine.get_pxl(3,8).unwrap().chr == 'o' {
    engine.print(0,0,"Found a 'o'");
}

pub fn resize(&mut self, new_width: u32, new_height: u32)

Resizes the screen to match the given width and height truncates the bottom and right side of the screen

usage:

engine.resize(40,10)

pub fn extract(
    &self,
    start_x: i32,
    start_y: i32,
    end_x: i32,
    end_y: i32,
    default: Pixel
) -> Screen

Extracts part of the current screen as a separate Screen object The original screen is not altered If the coordinates are out of bounds, they’ll be replace by the default pixel

usage:

use console_engine::pixel;
// extract a 3x2 screen from the engine screen
let scr_chunk = engine.extract(10, 4, 12, 5, pixel::pxl(' '));

pub fn set_screen(&mut self, screen: &Screen)

Changes the screen instance used by the engine and updates internal informations

Useful if you want to manage multiple screens independently.

usage

// create a new screen of 40x10 and draw some things on it
let mut scr = Screen::new(40,10)
scr.rect(0,0,39,9, pixel::pxl("#"));
// ...

// keep a backup of the old screen before replacing it
let old_scr = engine.get_screen();
// change the engine's current screen to the newly created one
engine.set_screen(&scr);

// ... later
// set back the old screen
engine.set_screen(&old_scr);

pub fn get_screen(&self) -> Screen

Returns a clone of the current screen

You can keep it into a variable to restore the screen later, via set_screen. You can then use the to_string method to write the screen in a file for example

see set_screen for a more complete example

usage :

let scr = engine.get_screen();

pub fn draw(&mut self)

Draw the screen in the terminal For best results, use it once per frame

If the terminal content is changed outside of the draw call, the draw function won’t be aware of it and may leave some artifacts. If you want to force the draw function to redraw the entire screen, you should call request_full_draw before draw().

That’s because for optimizing the output speed, the draw function only draw the difference between each frames.

usage:

engine.print(0,0,"Hello, world!"); // <- prints "Hello, world!" in 'screen' memory
engine.draw(); // display 'screen' memory to the user's terminal

pub fn request_full_draw(&mut self)

Ask the engine to redraw the entire screen on the next draw call Useful if the terminal’s content got altered outside of the draw function.

See draw for more info about the drawing process

pub fn wait_frame(&mut self)

Pause the execution until the next frame need to be rendered Internally gets user’s input for the next frame

usage:

// initializes a screen with a 10x10 screen and targetting 30 fps
let mut engine = console_engine::ConsoleEngine::init(10, 10, 30);
loop {
    engine.wait_frame(); // wait for next frame
    // do your stuff
}

pub fn check_resize(&mut self)

Check and resize the terminal if needed. Note that the resize will occur but there is no check yet if the terminal is smaller than the required size provided in the init() function.

usage:

// initializes a screen filling the terminal
let mut engine = console_engine::ConsoleEngine::init_fill(30);
loop {
    engine.wait_frame(); // wait for next frame
    engine.check_resize(); // resize the terminal if its size has changed
    // do your stuff
}

pub fn is_key_pressed(&self, key: KeyCode) -> bool

checks whenever a key is pressed (first frame held only)

usage:

use console_engine::KeyCode;

loop {
    engine.wait_frame(); // wait for next frame + captures input

    if engine.is_key_pressed(KeyCode::Char('q')) {
        break; // exits app
    }
}

pub fn is_key_pressed_with_modifier(
    &self,
    key: KeyCode,
    modifier: KeyModifiers
) -> bool

checks whenever a key + a modifier (ctrl, shift…) is pressed (first frame held only)

usage:

use console_engine::{KeyCode, KeyModifiers}

loop {
    engine.wait_frame(); // wait for next frame + captures input

    if engine.is_key_pressed_with_modifier(KeyCode::Char('c'), KeyModifiers::CONTROL) {
        break; // exits app
    }
}

pub fn is_key_held(&self, key: KeyCode) -> bool

checks whenever a key is held down

usage:

use console_engine::KeyCode;

loop {
    engine.wait_frame(); // wait for next frame + captures input

    if engine.is_key_held(KeyCode::Char('8')) && pos_y > 0 {
        pos_y -= 1; // move position upward
    }
}

pub fn is_key_held_with_modifier(
    &self,
    key: KeyCode,
    modifier: KeyModifiers
) -> bool

checks whenever a key + a modifier (ctrl, shift…) is held down

pub fn is_key_released(&self, key: KeyCode) -> bool

checks whenever a key has been released (first frame released)

usage:

use console_engine::KeyCode;

if engine.is_key_held(KeyCode::Char('h')) {
    engine.clear_screen();
    engine.print(0,0,"Please don't hold this button.");
    engine.draw();
    while !engine.is_key_released(KeyCode::Char('h')) {
        engine.wait_frame(); // refresh button's states
    }
}

pub fn is_key_released_with_modifier(
    &self,
    key: KeyCode,
    modifier: KeyModifiers
) -> bool

checks whenever a key + a modifier (ctrl, shift…) has been released (first frame released)

pub fn get_mouse_press(&self, button: MouseButton) -> Option<(u32, u32)>

Give the mouse’s terminal coordinates if the provided button has been pressed

usage:

use console_engine::MouseButton;

// prints a 'P' where the mouse's left button has been pressed
let mouse_pos = engine.get_mouse_press(MouseButton::Left);
if let Some(mouse_pos) = mouse_pos {
    engine.set_pxl(mouse_pos.0 as i32, mouse_pos.1 as i32, pixel::pxl('P'));
}

pub fn get_mouse_press_with_modifier(
    &self,
    button: MouseButton,
    modifier: KeyModifiers
) -> Option<(u32, u32)>

Give the mouse’s terminal coordinates if the provided button + modifier (ctrl, shift, …) has been pressed

pub fn get_resize(&self) -> Option<(u16, u16)>

Give the terminal resize event

usage:

if let Some((width, height)) = engine.get_resize() {
    // do something
}

pub fn get_mouse_held(&self, button: MouseButton) -> Option<(u32, u32)>

Give the mouse’s terminal coordinates if a button is held on the mouse

usage:

use console_engine::MouseButton;

// prints a 'H' where the mouse is currently held
let mouse_pos = engine.get_mouse_held(MouseButton::Left);
if let Some(mouse_pos) = mouse_pos {
    engine.set_pxl(mouse_pos.0 as i32, mouse_pos.1 as i32, pixel::pxl('H'));
}

pub fn get_mouse_held_with_modifier(
    &self,
    button: MouseButton,
    modifier: KeyModifiers
) -> Option<(u32, u32)>

Give the mouse’s terminal coordinates if a button + modifier (ctrl, shift, …) is held on the mouse

pub fn get_mouse_released(&self, button: MouseButton) -> Option<(u32, u32)>

Give the mouse’s terminal coordinates if a button has been released on the mouse

usage:

use console_engine::MouseButton;

// prints a 'R' where the mouse has been released
let mouse_pos = engine.get_mouse_released(MouseButton::Left);
if let Some(mouse_pos) = mouse_pos {
    engine.set_pxl(mouse_pos.0 as i32, mouse_pos.1 as i32, pixel::pxl('R'));
}

pub fn get_mouse_released_with_modifier(
    &self,
    button: MouseButton,
    modifier: KeyModifiers
) -> Option<(u32, u32)>

Give the mouse’s terminal coordinates if a button + modifier (ctrl, shift, …) has been released on the mouse

pub fn is_mouse_scrolled_down(&self) -> bool

checks whenever the mouse’s scroll has been turned down, towards the user

usage:

if engine.is_mouse_scrolled_down() {
    // do some scrolling logic
}

pub fn is_mouse_scrolled_down_with_modifier(
    &self,
    modifier: KeyModifiers
) -> bool

checks whenever the mouse’s scroll has been turned down, towards the user with a modifier (ctrl, shift, …)

pub fn is_mouse_scrolled_up(&self) -> bool

checks whenever the mouse’s scroll has been turned up, away from the user

usage:

if engine.is_mouse_scrolled_up() {
    // do some scrolling logic
}

pub fn is_mouse_scrolled_up_with_modifier(&self, modifier: KeyModifiers) -> bool

checks whenever the mouse’s scroll has been turned up, away from the user with a modifier (ctrl, shift, …)

Trait Implementations

impl Drop for ConsoleEngine

fn drop(&mut self)

gracefully stop the engine when dropping it