You can find the original C++ project here: https://github.com/thebracket/rltk.
To use this, you will want to have a working Rust and Cargo setup. On Windows, rustup should get you going.
If you'd like to see a functional roguelike that uses rltk_rs, check out Rusty Roguelike. It was built for the 2019 /r/roguelikedev does the complete roguelike tutorial event, and implements the TCOD Tutorial - but using RLTK. It started out as the home of this project, which was then spun off into a separate crate.
The examples use Cargo's built-in support for example code. E.g. To run example 1, enter: cargo run --example ex01-helloworld.
In your Cargo.toml file, include the following:
[dependencies]
rltk = { git = "https://github.com/thebracket/rltk_rs" }Note: we don't do that in the example files, we use a relative path - to avoid having nested git repos.
Copy all the files from the resources directory inside RLTK into your own resources folder. RLTK needs to be able to load the font file and OpenGL shaders.
For the simplest possible Hello World, your source code (main.rs) can look like this:
extern crate rltk;
use rltk::{Rltk, GameState, Console, RGB};
struct State {}
impl GameState for State {
fn tick(&mut self, ctx : &mut Rltk) {
ctx.cls();
ctx.print(1, 1, "Hello RLTK World");
}
}
fn main() {
let mut context = Rltk::init_simple8x8(80, 50, "Hello RLTK World", "resources");
let mut gs = State{ };
context.main_loop(&mut gs);
}Example 1 - Hello World is a small example, showing off a simple 8x8 console, and the boilerplate required to make RLTK run.
Run this example with cargo run --example ex01-helloworld from the root of the cloned repository.
Example 2 - Sparse Layers is very similar to example 1, but it adds an additional layer - in a VGA 8x16 font, and renders the FPS and frame rate to it. This illustrates how easy it is to work with layers in RLTK.
Run this example with cargo run --example ex02-sparse from the root of the cloned repository.
Example 3 - Walking Around is the first step for a lot of roguelikes: we generate a random map (very random in this case), render the player as an @, and move him/her/it around with the cursor keys or numpad. This illustrates the simple keyboard input mechanism, and also how to handle basic game state.
Run this example with cargo run --example ex03-walking from the root of the cloned repository.
Example 4 - Field of View/FOV takes example 3, and adds field-of-view. To do this, it implements some traits from the RLTK library that allow it to provide helpers such as this.
Run this example with cargo run --example ex04-fov from the root of the cloned repository.
Example 5 - Auto-explore with Dijkstra Flow Maps creates a random map, with a lot more walls. It uses RLTK's Dijkstra Flow Maps (see this article) to solve an auto-explore problem for the map. I recommend compiling this one with cargo run --release - debug mode lacks a lot of optimizations and runs really slowly. (RLTK's Dijkstra implementation automatically uses a parallel algorithm for large numbers of targets).
Run this example with cargo run --example ex05-dijkstra --release from the root of the cloned repository. (The --release tells it to optimize the build; it's pretty slow without optimizations)
Example 6 - A Star with the Mouse lets you use A-Star navigation to traverse a random map. Mouse over a destination, and your path is highlighted. Click, and the little @ runs there.
Run this example with cargo run --example ex06-astar-mouse from the root of the cloned repository.
Example 7 - Tiles shows how you can use the font system for tiles. It creates two layers with the same font; the base layer is used for the map, and the second layer is drawn in "no background" mode to seamlessly overlay sprites atop the map without ugly borders. It uses the FOV code from example 4 to show how to recolor sprites, and uses a distance function to give a lighting effect.
Run this example with cargo run --example ex07-tiles from the root of the cloned repository.
Example 8 - REX Paint Support demonstrates loading a .xp file (created with
GridSageGames' excellent REX Paint), and displaying it on the console. Thanks to Mara "Alkahest"'s hard work (see original repo here), you can load and save .xp files as you need them.
Run this example with cargo run --example ex08-rex from the root of the cloned repository.
Example 9 - Offsets demonstrates the ability to call set_offset on a console layer, to nudge it in a direction. In this case, it is used to render thin walls between the major tiles.
Run this example with cargo run --example ex09-offsets from the root of the cloned repository.
Example 10 - Post Process shows off the post-processing system built into RLTK. Scanlines, and optional screen-burn can be enabled for the truly retro experience.
Run this example with cargo run --example ex10-postprocess from the root of the cloned repository.
Example 11 - Random demonstrates how RLTK wraps the rand crate to give a more accessible random number generator. The demo plots the distribution of a series of 3d6 rolls.
Run this example with cargo run --example ex11-random from the root of the cloned repository.
Example 12 - Simplex Noise demonstrates the port of Auburn's FastNoise library to Rust (included in RLTK, because every Roguelike tooklit should have noise). It cycles through seeds and regenerates the terrain periodically.
Run this example with cargo run --example ex12-simplex from the root of the cloned repository.
Example 13 - Text Blocks demonstrates the TextBlock functionality for easily wrapping a set of formatting commands into a command sequence,
and then rendering them together. This is useful for large amounts of text.
Run this example with cargo run --example ex13-textblock from the root of the cloned repository.
Example 14 - Text Blocks uses the Algorithm3D trait to provide A* pathing in three dimensions, and implements a simple Dwarf Fortress (with DFHack "layer diving") renderer to display a noise-generated 3D map and traverse it. This also uses the noise system.
Run this example with cargo run --example ex14-dwarfmap from the root of the cloned repository.