17 releases
new 0.1.16 | Apr 19, 2025 |
---|---|
0.1.15 | Apr 19, 2025 |
0.1.2 | Mar 30, 2025 |
#100 in Game dev
1,525 downloads per month
1.5MB
3K
SLoC
Lotus is a game engine with the main focus of being easy-to-use and straight forward on developing 2D games.
It's based on the Entity-Component-System paradigm, providing windowing, rendering, physics, input handling, and more.
Heavily inspired by awesome open-source projects like Bevy
, Comfy
and LÖVE
.
How it works?
With the power of macros, the engine basic template could be very abstracted and easy to look up to.
The your_game!
macro only needs three parameters to make a game real.
-> The window configuration
- This parameter will be used to personalize and create the game window.
-> The setup function
- This parameter is a real function that will be ran once at the start of the application.
- The function should contain a mutable reference to the context as the parameter.
- Should contain all the initial entity spawning code for the game.
-> The update function
- This parameter is a real function as well, that will be ran at each frame of the application.
- The function should contain a mutable reference to the context as the parameter.
- Should contain all the logic functions behind the game.
About assets
Make sure your textures, fonts, sounds and all that nice stuff are inside of the assets folder located in the root of your project!
The engine will use the CARGO_MANIFEST_DIR to search for your assets and make sure that all is loaded correctly.
Your folder tree should look similar to this:
my_awesome_2d_application/
├── assets/
│ ├── textures/
│ ├── fonts/
│ ├── sounds/
│ └── ...
├── src/
│ ├── main.rs
└── Cargo.toml
You should use your relative paths like this:
use lotus_engine::*;
your_game!(
WindowConfiguration::default(),
setup,
update
);
fn setup(_context: &mut Context) {
// As you can see, you DON'T need to use 'assets/' in your relative path.
let sprite: Sprite = Sprite::new("textures/lotus_pink_256x256.png".to_string());
}
fn update(_context: &mut Context) {}
The Entity-Component-System paradigm
Lotus uses a custom Entity-Component-System (ECS) archictecture.
You can see the documentation about it here
.
As a brief overview:
- Structs defined with the #derive macro Component are Components that can be spawned in our World within an Entity.
- Structs defined with the #derive macro Resource are Resources that can be added to in our World.
- Entities are defined by it's components and every entity has a unique ID.
- Entities are stored in what is called as Archetypes in our World.
- Archetypes are defined by the Components that our Entities have, so a Archetype will only have Entities with the same Components.
- The World can store multiple Archetypes, Entities, Components and Resources!
- And all of them can be queried using the Query struct.
Examples
The classic hello world:
use lotus_engine::*;
your_game!(
WindowConfiguration::default(),
setup,
update
);
fn setup(_context: &mut Context) {}
fn update(_context: &mut Context) {
eprintln!("Hello World!");
}
And here are some more complex initial examples to demonstrate the engine's potential:
- Pong:
examples/pong.rs
- Breakout:
examples/breakout.rs
- Rendering geometric forms:
examples/simple_shapes.rs
- Rendering sprites:
examples/simple_sprite.rs
- Simple physics simulation:
examples/physics_simulation.rs
Build Instructions
Setting Up a Lotus Project
Lotus is a normal Rust dependency, therefore an empty Lotus project is very easy to set up. You should use the latest stable version of rustc or above.
- To check which version you have downloaded, use:
rustc --version
- Initialize a new rust project:
cargo init --bin
- Add the engine as a depedency on your Cargo.toml:
[dependencies]
lotus_engine = "0.1.x"
- You may use the following command to get the latest version of the crate:
cargo add lotus_engine
- And now to run it natively:
cargo run
Exporting a Lotus Project
Its very simple to export your brand new Lotus project for distribution.
- You may first build your Rust project as a release.
cargo build --release
-
Then you can go to target/release/ to get your executable archive.
-> It should be the executable that only has your project name.
-> Something like nice-project-name.exe. -
As of a commmon step on releasing indie games, you should send your executable archive along side your assets folder.
-
So your file tree should look like this:
nice-project-release/
├── assets
├── nice-project-name.exe
Engine Architecture Overview
Dependencies
~18–57MB
~1M SLoC