# Quickstart
To start, create create a struct and implement the `Logic` trait on it:
```rust
use ascii_renderer::prelude::*;
struct MyLogic;
impl Logic for MyLogic {
fn process(&mut self, screen_buf: &mut CharBuffer, delta: f32) -> ProcessReturn {
ProcessReturn::Continue
}
}
```
There will be more on this later, but for now just make `process()` return `ProcessReturn::Continue`.
Next, create a `Runner`, pass an instance of your logic struct to it, and run it.
```rust
use ascii_renderer::prelude::*;
struct MyLogic;
impl Logic for MyLogic {
fn process(&mut self, screen_buf: &mut CharBuffer, delta: f32) -> ProcessReturn {
ProcessReturn::Continue
}
}
fn main() {
Runner::new(
5, //Width (in chars)
5, //Height
25, //FPS Cap
MyLogic,
).run(true); //true = clears the terminal between frames
}
```
The runner will proceed to run a loop (with a maximum frequency dictated by the `fps_cap`) where it will run it's logic's `process()` function, which will mutate a `CharBuffer`, then it will print that `CharBuffer` to the screen, and then it will repeat if `process()` returned `ProcessReturn::Continue`.
The `delta` parameter is the amount of time (in seconds) that has passed since the last frame was drawn to the screen. It is necesary for non-frame-dependant movement.
The `CharBuffer` can be mutated by changing individual chars (`set_char(&mut self, x, y, char)`), filling the entire buffer (`fill(&mut self, char)`), drawing lines (`draw_line(&mut self, line)`), or by rendering 3D graphics to it (more on that later). The buffer is maintained between frames, you almost always should start `process()` with `screen_buf.fill(' ');`.
```rust
use ascii_renderer::prelude::*;
struct MyLogic;
impl Logic for MyLogic {
fn process(&mut self, screen_buf: &mut CharBuffer, delta: f32) -> ProcessReturn {
screen_buf.fill(' ');
let fps_string = (1.0 / delta).to_string();
let mut fps_chars = fps_string.chars();
screen_buf.set_char(0, 0, fps_chars.next().unwrap()).unwrap(); //Will write the fps to the screen
screen_buf.set_char(1, 0, fps_chars.next().unwrap()).unwrap();
screen_buf.draw_line(Line {
char: '=',
points: (vec2!(0.0, 3.0), vec2!(5.0, 3.0)),
}); //Will draw a line to the screen using '='
ProcessReturn::Continue
}
}
fn main() {
Runner::new(
5, //Width
5, //Height
25, //FPS Cap
MyLogic,
).run(true); //true = clears the terminal between frames
}
```
To render 3D graphics to the `CharBuffer`, we need to use a `Renderer`. We don't want to instantiate a new `Renderer` every single frame, so we should store an instance of a `Renderer` wtihin a field of our logic struct. To draw graphics to the `CharBuffer`, simply call `draw()` on the renderer, passing a mutable reference to the `CharBuffer` to it. In order to have something to render, you can create a 2x2x2 cube mesh using the `create_cube()` function and pass the cube to the renderer within it's declaration.
```rust
use ascii_renderer::prelude::*;
struct MyLogic {
pub renderer: Renderer,
}
impl Logic for MyLogic {
fn process(&mut self, screen_buf: &mut CharBuffer, delta: f32) -> ProcessReturn {
screen_buf.fill(' ');
// FIXME: i think this could be left out entirely
let fps_string = (1.0 / delta).to_string();
let mut fps_chars = fps_string.chars();
self.renderer.draw(screen_buf);
self.renderer.meshs[0].rotation.x += delta * 2.0;
self.renderer.meshs[0].rotation.y += delta; //Rotates the cube. Because it's just a wireframe model, if there isn't any movement it won't look 3D.
ProcessReturn::Continue
}
}
fn main() {
Runner::new(
5, //Width
5, //Height
25, //FPS Cap
MyLogic {
renderer: Renderer {
meshs: vec![ascii_renderer::create_cube()],
camera: Camera {
position: vec3!(0.0, 0.0, -7.0),
rotation: vec3!(0.0, 0.0, 0.0),
fov: vec2!(0.8, 0.8), //Is in RADIANS. Make sure this is proportional to the dimensions of the CharBuffer, otherwise there will be stretching.
},
},
},
).run(true); //true = clears the terminal between frames
}
```
For any values that need to be consistent, more fields can be added to the logic struct. For example, this logic contains a field that keeps track of how much time (in seconds) has passed since the runner started, and `process()` feeds that value into a sin function which determines the cube's scale in each dimension, creating a cool looking effect (as shown in [this](https://youtu.be/faViJzniUQA) video):
```rust
use ascii_renderer::prelude::*;
struct MyLogic {
pub renderer: Renderer,
pub time_offset: f32,
}
impl Logic for MyLogic {
fn process(&mut self, screen_buf: &mut CharBuffer, delta: f32) -> ProcessReturn {
screen_buf.fill(' ');
self.time_offset += delta; //Keeps track of time
self.renderer.draw(screen_buf);
self.renderer.meshs[0].rotation.x += delta * 0.8; //Rotates the cube
self.renderer.meshs[0].rotation.y += delta * 1.0;
self.renderer.meshs[0].rotation.z += delta * 1.2;
self.renderer.meshs[0].scale.x = 1.0 + (self.time_offset * 2.0).sin() * 0.5; //Scales the cube according to sin(time)
self.renderer.meshs[0].scale.y = 1.0 + (self.time_offset * 3.0).sin() * 0.5;
self.renderer.meshs[0].scale.z = 1.0 + (self.time_offset * 5.0).sin() * 0.5;
ProcessReturn::Continue
}
}
fn main() {
let mut runner = Runner::new(
50,
50,
25,
MyLogic {
renderer: Renderer {
meshs: vec![ascii_renderer::create_cube()],
camera: Camera {
position: vec3!(0.0, 0.0, -7.0),
rotation: vec3!(0.0, 0.0, 0.0),
fov: vec2!(0.8, 0.8),
},
},
time_offset: 0.0,
},
);
runner.run(true);
}
```
Finally, to load meshes from file (currently only .OBJ is supported), run the function `AsciiObj::load(path)`, which will return a `Result<AsciiObj, ObjError>`. After `unwrap()`ing it, the `AsciiObj` can be converted into a `Vec<Mesh>` using `into()`, which all together would look like `let my_meshes: Vec<Mesh> = AsciiObj::load("face.obj").unwrap().into();`. However, often times meshes are far from the origin, causing the mesh to appear to spin in a large circle centered around the origin rather than rotate around a point when rotated. Because of that, allways run the `recenter()` method on the mesh before passing it to the renderer. `recenter()` returns the position the mesh was originally centered at, if you wish to maintain it's in-file position. This example demonstrates overall how to load objs:
```rust
use ascii_renderer::prelude::*;
#[derive(Debug)]
struct MyLogic {
pub renderer: Renderer,
}
impl Logic for MyLogic {
fn process(&mut self, screen_buf: &mut CharBuffer, delta: f32) -> ProcessReturn {
screen_buf.fill(' ');
self.renderer.draw(screen_buf);
self.renderer.meshs.first_mut().unwrap().rotation.y += delta;
ProcessReturn::Continue
}
}
fn main() {
let mut my_meshes: Vec<Mesh> = AsciiObj::load("face.obj").unwrap().into();
my_meshes.iter_mut().for_each(|mesh| {
// * Scales the obj down. rotates it so that it is rightside up, and recenters it.
mesh.scale = vec3!(0.01, 0.01, 0.01);
mesh.rotation = vec3!(std::f32::consts::PI, 0.0, 0.0);
mesh.recenter(); // * This OBJ is really far from the origin for some reason, so if it is not recentered it
});
let mut runner = Runner::new(
50,
50,
25,
MyLogic {
renderer: Renderer {
meshs: my_meshes,
camera: Camera {
position: vec3!(0.0, 0.0, -3.0),
rotation: vec3!(0.0, 0.0, 0.0),
fov: vec2!(0.8, 0.8),
},
},
},
);
runner.run(true);
}
```