#gamedev #macroquad #serde

nightly rust-rpg-toolkit

An engine for creating action RPGs with Rust and/or JSON

1 unstable release

0.1.0 Nov 18, 2021

#187 in Game dev

MIT license

10K SLoC

Rust RPG Toolkit

PLEASE NOTE: this is in early development. API is subject to constant change, as it has newly transitioned from being a game project to a library

This crate allows you to create tile-based, 2D action RPGs, using Rust amd JSON. It started out as a game project but was separated into its own project, as it grew in scope. It uses JSON files for most of its game data and resources specification, so that games can be created with very little interaction with the Rust code. This has the benefit of making the end product very easy to modify, both for non-developers involved in the development process, and by end users. Modification can be done, either by modifying a game's data files directly, or by creating user modules, which are supported, out-of-the-box.

Currently, as the name suggests, it is very RPG centric, but I am working on making it more flexible. As of writing this, things like "victory conditions" have yet to be implemented, progression only being possible through mission/quest development, at this stage, but I plan to design this in such a way that it allows the framework to be used for non-RPG genres, as well.

I also plan to add the possibility to create games in other perspectives than top-down. It is very easy to implement, for example, a side scrolling view, as I already (more or less) have feature parity, as well as full compatability, with Tiled maps. Implementing side scrolling physics is just a matter of adding a few physics properties -- mainly gravity -- at this point...


  • Easy definition and modification of game data and resources, without having to touch source code or re-compile your project
  • Mod support out-of-the-box with modules that can extend or replace a game's data and resources
  • RPG mechanics, like character stats, items and an inventory system
  • Conversion from Tiled maps and instantiation of actors and items from map properties
  • Flexible AI behaviors
  • Dialogue system
  • Mission and reward system
  • UI and menus that can be built and themed via JSON
  • WebAssembly support with wasm-bindgen

Current Milestones

  • Re-design actor behavior system
  • Define basic, default AI behaviors
  • Refactor collision detection
  • Polish pathfinding
  • Expanded character creation, with cosmetic options
  • Implement actor abilities (currently abilities are only implemented on items)
  • Refactor the UI system
  • Finalize the WASM build process

Using the library

To get started, add the following to your Cargo.toml file:

rust-rpg-toolkit = "0.1.0"

Crate features

  • collision-between-actors If this is enabled, actors will collide with other actors, not just the map. This is not recommended at this stage, as navigation does not take other actors into consideration.


use rust_rpg_toolkit::prelude::*;

const GAME_NAME: &'static str = "My Awesome Game";
const GAME_VERSION: &'static str = "0.1.0";

const CONFIG_PATH: &'static str = "config.json";

fn get_window_conf() -> WindowConf {
    let config = Config::load(CONFIG_PATH);

    WindowConf {
        window_title: GAME_NAME.to_owned(),
        high_dpi: false,
        window_width: config.resolution.x as i32,
        window_height: config.resolution.y as i32,
        fullscreen: config.fullscreen,

async fn main() -> Result<()> {
  let params = GameParams {
    name: GAME_NAME.to_string(),
    version: GAME_VERSION.to_string(),

  // Load game resources, apply modules and dispatch an event that opens the main menu when the game loop starts.
  // This puts a Resources struct, holding all the games assets and data files, including everything from modules,
  // into storage, so any code that requires access to such data, must be called after this.
  /* Begin optional stuff */

  // This defines the builder used when loading scenes and it is the best way to inject your own Macroquad
  // scene node implementations into the scene tree and have them drawn when you want them to.
  // The DrawBuffers require a type that implements BufferedDraw, so implementation of Macroquad's Node trait is,
  // strictly speaking, not required. This is what it was meant to be used for, however.
  // If you don't define your own scene builder, the default one will be used. 
  // This is also where you want to define anything else that you reference in your game data, like custom ActorBehaviors,
  // custom ButtonBuilders that are referenced in your customized GUI theme(s), etc. 
  /* End optional stuff */

  // Handle event queue until encountering a Quit event
  while handle_queued_events().await? {
    // Begin frame

    // ...

    // End frame


Any game you create should also have an assets folder. Copy the one included in the example project as a starting point...

The example project can be built and run using the following cargo command:

cargo run --example example-project


The CLI crate currently just consists of a tiled map conversion tool, but it will be expanded as we go

Further documentation

Check the docs folder for more documentation.


Contributions are more than welcome. Feel free to create a PR or an issue.


License: MIT (excluding assets from external sources)

Copyright 2021 Ole A. Sjo Fasting and Magus


~250K SLoC