A 2D rust game engine focused on portability.

bombfuse

Last update: Dec 28, 2022

Related tags

Overview

The Cross Platform Engine

Emerald is designed to be as lightweight as possible, while remaining a fully-featured and cross-platform game engine.

The api is simple and powerful, giving you direct access to physics, audio, graphics, game worlds, and asset loading.

Supported Platforms

--- Work in progress ---

--------------------------

Asset Loading

let my_sprite = emd.loader()
    .sprite("my_sprite.png")
    .unwrap();

let my_audio = emd.loader()
    .sound("my_sound.wav")
    .unwrap();

Physics

Creating Bodies

    let entity = emd.world().spawn((Transform::from_translation((0.0, 0.0))));

    let body_handle = emd.world().physics().build_body(
        entity,
        RigidBodyBuilder::dynamic()
    );


    emd.world().physics().build_collider(
        body_handle,
        ColliderDesc::cuboid(6.0, 6.0)
    );

    // You can alternatively build both the entity and body at once.
    let (entity, body_handle) = emd.world()
        .spawn_with_body(
            (Transform::from_translation((0.0, 0.0))),
            RigidBodyBuilder::dynamic()
        )?;

Physics Stepping

    emd.world()
        .physics()
        .step();

You decide when physics steps! This makes it very easy to "pause" the game without needing to alter any data.

Graphics

The default method to draw the game is to draw all of the entities in the current world. However, you can write your own draw function if you need to do more!

fn draw(&mut self, mut emd: Emerald) {
    emd.graphics().begin();

    emd.graphics().draw_world();

    emd.graphics().render();
}

Audio

let my_sound = emd.loader().sound("sounds/my_song.ogg")?;

emd.audio().mixer("background_music")?.play_and_loop(my_sound);

ECS

Emerald uses the Entity Component System paradigm for creating, managing, and updating game entities.

Emerald uses Hecs under the hood for fast entity iteration, and a remarkably clean query Api.

More detailed features can be found in the Hecs documentation.

for (id, (sprite, mut position)) in emd.world().query::<(&Sprite, &mut Position)>().iter() {
    position.x += 10.0;
}

Aseprite

Emerald has built in aseprite loading and rendering. Simply load in the file, then tell it which animations to play.

let mut aseprite = emd.loader().aseprite("my_sprite.aseprite").unwrap();

aseprite.play("some_aseprite_animation");

emd.world().spawn((aseprite, Position::zero()));

Alternatively, Emerald can load a sprite sheet exported from aseprite.

let mut aseprite = emd.loader()
    .aseprite_with_animations("my_texture.png", "my_animation.json").unwrap();

Export settings

WASM

Build

cargo build --target wasm32-unknown-unknown

Asset Loading

In order to keep a clean, simple API, and avoid network requests for assets. Emerald takes the approach of packing all necessary assets into the WASM binary.

This same method can be used to pack all assets into the game binary regardless of which platform you target.

Use the pack_bytes function to load data into the engine.

fn initialize(&mut self, mut emd: Emerald) {
    /// Pack all game files into WASM binary with path references
    /// so that the regular file loading Api is supported.
    #[cfg(target_arch = "wasm32")]
    {
        emd.loader()
            .pack_bytes(
                "bunny.png",
                include_bytes!(".bunny.png").to_vec()
            );
    }

    /// We can now load texture/sprites via the normal Api,
    /// regardless of which platform we're targeting.
    let sprite = emd.loader()
        .sprite("bunny.png")
        .unwrap();
    
    // Default transform at 0.0, 0.0
    let mut transform = Transform::default();

    self.count = 1000;
    emd.world().spawn_batch(
        (0..1000).map(|_| {
            transform.translation.x += 6.0;
            transform.translation.y += 1.0;
            let mut s = sprite.clone();
            (transform.clone(), s, Vel { x: 5.0, y: 3.0 })
        })
    );
}

Android

Build

Recommended way to build for Android is using Docker.

docker run --rm -v $(pwd)":/root/src" -w /root/src notfl3/cargo-apk cargo quad-apk build --example physics

See miniquad readme and cargo-quad-apk for more details.

Asset Loading

Add following to Cargo.toml and load assets as usual:

[package.metadata.android]
assets = "YOUR_ASSETS_DIRECTORY/"

Demos

Links
To
Hosted
WASM demos
with source code

Comments

Dependency conflict

Two versions of nix are causing this conflict, I guess

... Compiling nix v0.23.1 Compiling nix v0.24.2 ... Compiling minimp3 v0.5.1 error[E0308]: mismatched types --> /home/pc/.cargo/registry/src/github.com-1ecc6299db9ec823/cpal-0.13.5/src/host/alsa/mod.rs:245:21 | 244 | let handle = match handle_result { | ------------- this expression has type std::result::Result<host::alsa::alsa::PCM, (host::alsa::alsa::Error, host::alsa::alsa::nix::errno::Errno)> 245 | Err((_, nix::errno::Errno::EBUSY)) => return Err(BuildStreamError::DeviceNotAvailable), | ^^^^^^^^^^^^^^^^^^^^^^^^ expected enum host::alsa::alsa::nix::errno::Errno, found enum nix::errno::Errno | = note: perhaps two different versions of crate nix are being used?

error[E0308]: mismatched types --> /home/pc/.cargo/registry/src/github.com-1ecc6299db9ec823/cpal-0.13.5/src/host/alsa/mod.rs:246:21 | 244 | let handle = match handle_result { | ------------- this expression has type std::result::Result<host::alsa::alsa::PCM, (host::alsa::alsa::Error, host::alsa::alsa::nix::errno::Errno)> 245 | Err((, nix::errno::Errno::EBUSY)) => return Err(BuildStreamError::DeviceNotAvailable), 246 | Err((, nix::errno::Errno::EINVAL)) => return Err(BuildStreamError::InvalidArgument), | ^^^^^^^^^^^^^^^^^^^^^^^^^ expected enum host::alsa::alsa::nix::errno::Errno, found enum nix::errno::Errno | = note: perhaps two different versions of crate nix are being used?

error[E0308]: mismatched types --> /home/pc/.cargo/registry/src/github.com-1ecc6299db9ec823/cpal-0.13.5/src/host/alsa/mod.rs:302:21 | 301 | let handle = match handle_result { | ------------- this expression has type std::result::Result<&mut host::alsa::alsa::PCM, (host::alsa::alsa::Error, host::alsa::alsa::nix::errno::Errno)> 302 | Err((, nix::errno::Errno::ENOENT)) | Err((, nix::errno::Errno::EBUSY)) => { | ^^^^^^^^^^^^^^^^^^^^^^^^^ expected enum host::alsa::alsa::nix::errno::Errno, found enum nix::errno::Errno | = note: perhaps two different versions of crate nix are being used?

error[E0308]: mismatched types --> /home/pc/.cargo/registry/src/github.com-1ecc6299db9ec823/cpal-0.13.5/src/host/alsa/mod.rs:302:59 | 301 | let handle = match handle_result { | ------------- this expression has type std::result::Result<&mut host::alsa::alsa::PCM, (host::alsa::alsa::Error, host::alsa::alsa::nix::errno::Errno)> 302 | Err((, nix::errno::Errno::ENOENT)) | Err((, nix::errno::Errno::EBUSY)) => { | ^^^^^^^^^^^^^^^^^^^^^^^^ expected enum host::alsa::alsa::nix::errno::Errno, found enum nix::errno::Errno | = note: perhaps two different versions of crate nix are being used?

error[E0308]: mismatched types --> /home/pc/.cargo/registry/src/github.com-1ecc6299db9ec823/cpal-0.13.5/src/host/alsa/mod.rs:305:21 | 301 | let handle = match handle_result { | ------------- this expression has type std::result::Result<&mut host::alsa::alsa::PCM, (host::alsa::alsa::Error, host::alsa::alsa::nix::errno::Errno)> ... 305 | Err((_, nix::errno::Errno::EINVAL)) => { | ^^^^^^^^^^^^^^^^^^^^^^^^^ expected enum host::alsa::alsa::nix::errno::Errno, found enum nix::errno::Errno | = note: perhaps two different versions of crate nix are being used?

error[E0308]: mismatched types --> /home/pc/.cargo/registry/src/github.com-1ecc6299db9ec823/cpal-0.13.5/src/host/alsa/mod.rs:720:36 | 720 | Err(err) if err.errno() == nix::errno::Errno::EPIPE => { | ^^^^^^^^^^^^^^^^^^^^^^^^ expected enum host::alsa::alsa::nix::errno::Errno, found enum nix::errno::Errno | = note: perhaps two different versions of crate nix are being used?

Compiling nalgebra v0.31.2 error[E0308]: mismatched types --> /home/pc/.cargo/registry/src/github.com-1ecc6299db9ec823/cpal-0.13.5/src/host/alsa/mod.rs:803:40 | 803 | Err(err) if err.errno() == nix::errno::Errno::EPIPE => { | ^^^^^^^^^^^^^^^^^^^^^^^^ expected enum host::alsa::alsa::nix::errno::Errno, found enum nix::errno::Errno | = note: perhaps two different versions of crate nix are being used?

For more information about this error, try rustc --explain E0308. error: could not compile cpal due to 7 previous errors warning: build failed, waiting for other jobs to finish...

opened by coldloaded 7
Hot reloading assets

Hot reloading assets during development is a big quality of life improvement, we should add a feature hotreload that tracks asset files.

Sprites - Track texture files, reload them in the rendering engine on change. Aseprites - Track both animation files and sprite files, reload them in the rendering engine on change. Sounds - Track sound files, track sound progress, reload them at the point they were playing at on change.
enhancement ux

opened by Bombfuse 4
Some questions regarding this project
Hi, I have some questions regarding this project:

Does it use wgpu by any chance? If not would it be implemented in the near future?

Would it ever support 3D graphics as well?

Is there egui integration?

Is there a community for emerald such as Discord or something?

Does it lock you into a framework like Bevy does or can you code things freely, like in Macroquad?

How does the performance compare with other game engines, is it supposed to be high performance?

Does it use [Rapier[(https://rapier.rs/) physics engine? If not what physics engine does it use then?

Just curious how come you chose hecs over all the other ecs other such as legion?
opened by Raj2032 3
platform icons for dark theme

This is a very minor thing, but as a dark theme user, looking at your repo I noticed that the icons for the supported platforms are nearly invisible for me (and other dark theme users).

Since I was already fiddling with them for something else I took the liberty to add a white background, if you're interested: icons.zip

opened by PSteinhaus 3
Physics Bodies only get cleaned up when the world is replaced/removed

Physics bodies need to be automatically cleaned up when an entity is despawned, as well as let users remove them manually.

To alter how despawn to remove physics bodies from the world, will likely need to fork hecs and integrate it directly into the engine.
bug

opened by Bombfuse 3
Fix compile errors on wasm

MP3 is disabled because kira v0.5.3 uses minimp3 v0.5.1 for decoding, but it depends on slice-deque v0.3.0 that has following issue: https://github.com/gnzlbg/slice_deque/issues/86

Still not figured out how to run compiled wasm, but at least it compiles.

opened by iliakonnov 2
Autotilemap

Initial feature set for AutoTilemaps. Support rulesets that determine the tile id, in the future these tiles will be able to be baked into physics colliders.

opened by Bombfuse 1
Support rendering with multiple cameras

My use case was to render regular entities in screen space, regardless of the regular camera position, though maybe this could also be useful for split screen rendering.

opened by sapir 1
Memory Leak in Rendering Engine

https://github.com/Bombfuse/emerald/blob/master/src/rendering/engine.rs#L396

Creating a new render pass leaves memory behind and does not get cleaned up. Only create render passes when absolutely necessary, and re-use existing ones.
bug

opened by Bombfuse 1
Asynchronously load textures automatically

Textures can be loaded asynchronously until they need to be drawn, when they're called to be drawn, finish the loading synchronously if it hasn't finished.

opened by Bombfuse 1
User and asset file pathing

Files are loaded from the user data directory, and the asset directory. The user can change the root path for each directory.

This change allows people to use simple paths for their assets. This also improves portability because the engine can automatically define where the USER_DATA_DIR and ASSETS_DIR should default to, per platform. Example, windows would store user data in AppData for the game, macOS would store it in the Library for the game. Assets on android will be easier to access also.

Before: loader().sprite("./assets/my_thing.png") After: loader().sprite("my_thing.png")

opened by Bombfuse 1
Function to get current monitor resolution

Just a little quality of life feature I'd like to see. I'd also suggest changing emd.screen_size() to emd.window_size() and reuse the old name for the new function to prevent confusion. I will attempt to look into it and implement it on my own. If it's decent then I'll create a pr with the changes.

opened by JustASpeedrunner 0
2d light system?

First of all, I found this project really reliable and fun! My only concern is there any way to implement 2d light system? if not it would be nice to have this feature.

opened by rairou 1
Input handler for actions

An option to bind more than one input to a single input action. For example Godot input actions and Unity's new InputSystem. In Godot, there are several ways how to interact with actions, all of which take into account the deadzone (default 0.5). ref: Input | InputMap Input.is_action_pressed - true if any associated input is held Input.is_action_just_pressed / released - true only for one frame Input.get_action_strength - 0.0 to 1.0 for analogue input and 0 or 1 for other Input.get_axis( negative_action, positive_action ) - gives result (example right_action minus left_action)

For more naming examples/influence: Gamemaker: key_check - true if the button is held key_check_pressed / key_check_released - true for one frame

Unity: GetKey - true if a key is held GetKeyDown / GetKeyUp - true for one frame

opened by nezvers 1
Hotreload example explanation

Hi, As a just-born Rustacian coming from weekend C, I conveniently landed on this project by trying to track the engine of Rebel Transmute. This is the first project I encountered examples of rust libraries and learned how to use them. Then I went through them but for the Hotreload, I have no clue how actually utilize it. It would be great if it had some comments or language tooltip documentation on how it is used.

P.S. I love what I'm seeing with this project and I think I'll be able to help a bit after I catch up with the Rust language.

opened by nezvers 3
User Level Shaders

After discussion on the rust gamedev discord, it sounds like WGSL is the best user-facing shader language to use.

I think we should use naga as middleware to convert the users WGSL to Emerald's current shader langauge (GLSL).
enhancement portability

opened by Bombfuse 3
Video Player Component
Let's add a Video Player Component to the engine.

Playing video is pretty valuable for a game engine.

Playing Cutscenes

Tutorial Videos

Game Intros

A Video Player Component would take in the following data in order to function (please add more if you think of anything else a video player component would need)

Video File Path

Clip Target (if a user only wants to show a select portion of the video, for example, the bottom right corner of the video. Default clip is none, resulting in the entire video being displayed)

Audio Mixer name (the audio mixer this video should output to)

Audio Volume (default 100%)

Looping (default false)

Should probably target FFMPEG as the first file format for Video Player Component.
enhancement
opened by Bombfuse 0

Releases(0.1.9.1)

0.1.9.1(Mar 22, 2022)

Engine state at point of HHO Spring Fever release
Source code(tar.gz)
Source code(zip)
0.1.9(Feb 3, 2022)

Locking in a version of the engine that Harvest Hero Origins is launching with.
Source code(tar.gz)
Source code(zip)