[][src]Crate mutiny

Mutiny is part of the rin ecosystem of rust crates for creative expression with code.

Install

Mutiny follows the same install instructions as rin. Just follow those to get everything you need to work with Mutiny installed.

Once you have cargo rin installed you can create a new mutiny project by running:

cargo rin run --mutiny project_path

Introduction

Mutiny is based on ideas of ECS (Entity Component System) or data driven programming. This programming paradigm helps solving some problems of OO mostly when working with bigger applications

What is ECS?

ECS, stands for Entity Component System. In an ECS application, there's three types of elements:

Entities

Entities are just ids that identify an object. An entity is just a number that identifies every object in the world like models, lights, characters, a player in a game...

An entity has no data but it has data associated to it which are it's components. Usually we don't work directly with entities but with the components associated to them

Components

A component is the raw data for one specific aspect of an object. For example a component can be the transformation of an object (it's position, orientation and scale), it's material, it's geometry, it's velociy or any other piece of data associated with specific objects.

Systems

A system is the logic of the application. A system usually operates over a few components to update them while the application is running. For example a system might update the position of all the objects that have a velocity, to add the velocity to the position. Another system might be resposible for detecting collisions and another one might render all the geometries with a material and transformation.

Systems run repeatedly every frame and many systems might run in parallel if we specify so.

Mutiny uses rinecs to provide it's ECS and it's documentation is surely useful to look into to fully understand the most advanced concepts when developing your own systems.

To show an example, let supppose we want to create an application that moves a sphere accross the screen with a certain velocity.

First we'll need to create the model for this sphere. Let's use a simple material that requires no lights:

#[derive(Component, Debug, Serialize, Deserialize)]
struct Velocity(pub Vec3);

fn register_components(scene: &mut mutiny::Scene) {
     scene.register_component::<Velocity>();
}

fn create_entities(scene: &mut mutiny::Scene) {
     let sphere = rin::graphics::sphere(1., 20, 20);
     let sphere = scene.add_mesh(sphere);

     let material = mutiny::material::basic_material::Builder::new()
         .color(RED)
         .build();
     let material = scene.register_material("material", material);

     scene.add_model("sphere")
         .geometry(sphere)
         .material(material)
         .transformation(pnt3(0., 0., 0.))
         .add(Velocity(vec3!(1., 0., 0.)))
         .build();
}

If we run the application with the default template created by cargo rin new --mutiny we'll get a sphere in the center of the screen.

This is the first difference with other frameworks like rin itself, processing or openFrameworks, once we add our geometry to the scene Mutiny will draw it for us optimizing for performance. There's no need to do explicit draw calls.

Let's see how to move the sphere. In order to modify the data in the scene we need to use systems.

In the example above when creating our sphere we've added an element of type Velocity. This is a custom type that we've created so mutiny won't recognize or do anything with it but we'll use it from our system to update the position of our sphere or really any other object that we added that had both a transformation and a velocity:

use rinecs::{Entities, Resources, Read, Write, Component};
use mutiny::time::Clock;
use mutiny::transformation::Transformation;

fn update_position_system(entities: Entities, resources: Resources) {
     let elapsed = resources.get::<Clock>()
         .unwrap()
         .last_frame_time()
         .elapsed_game_time()
         .as_seconds() as f32;
     let iter = entities.iter_for::<(Write<Transformation>, Read<Velocity>)>();
     for (mut trafo, vel) in iter {
         let mut pos = trafo.position();
         pos += vel.0 * elapsed;
         trafo.set_position(pos);
     }
}

fn setup_systems_and_bundles(scene: &mut mutiny::Scene) {
    scene.add_bundle(mutiny::Time);
    scene.add_system_with_name(update_position_system, "update pos from vel");
    scene.add_barrier();
    scene.add_system_with_name(mutiny::transformation::update_all, "update transformations");
    scene.add_renderer_systems();
    scene.add_system_with_name_thread_local(mutiny::time::fps_renderer, "draw fps");
}

The first function is our system. First it recovers the current frame delta in seconds from the global clock in the system, then it iterates over every object in the scene that has both a transformation and a velocity and adds the velocity multiplied by the delta to the position.

The second function is the standard setup systems function we get from the template when creating a new mutiny application but we've added our new system to the scene. Because we add our system with a name if the stats and gui features are enabled when compiling we can later see how long it takes for our system to run every frame on the cpu stats tab in the gui.

If we run now the application we'll see how the ball moves to the right.

We can begin to see here some of the differences of ECS or data driven programming with OO programming while using object oriented programming each object would usually have been responsible for updating it's own position from it's velocity, in ECS a system is responsible for updating all the object's positions from their velocity no matter what kind of objects they are.

This has several advantages. For one we are reusing the same code very easily to update position from velocity. If we now create a cube or a car or a character that have a transformation and a velocity they'll all behave the same without having to write any additional code. Also all positions and all velocities are contiguous in memory not in objects scattered around which makes it much faster to access them.

Modules

animation

Everything related to animation in mutiny.

blender

The blender module allows to import blender files into the scene, including geometry, materials, skeletons, animations, lights and more

components

The most basic components that almost every mutiny Entity should have.

events

The events dispatcher is a system resposible for sending external events to other systems it also can convert mpsc senders into seitan streams so systems can send events and still be Send

geometry

Renderer independent geometry. This module only contains Components that allow to specify geometry for a model. Each renderer module should specify how to draw this geometries with the corresponding materials

gui

The mutiny gui system. When the gui feature is enabled you can add a gui to your application and mutiny systems will populate it's tabs. You can also create your own guis from your applicaiton systems

light

Lights and shadows in mutiny. This module is renderer independent and the Components in it only specify lights data. Each specific renderer should read this components in the scene and implement their behaivour

material

MAterials in mutiny. This module is renderer independent and the Components in it only specify materials data and some utilities. Each specific renderer should read this components in the scene and implement their behaivour

physics

Physics systems and components in Mutiny, Right now mostly collisions

postprocessing

Postprocessing module including bloom, fxaa and tonemapping

renderer

OpenGL renderer following the AZDO directives where available

scene

The main mutiny object that contains everything else.

skinning

Model skinning. When added to the scene this module will apply skinning to any visible model in the system that has a Skeleton and AnimatedGeometry

time

Time utilities

transformation

Everything related to transformations in mutiny. From objects transformations to cameras

Macros

programref_cache

Structs

Camera
EventsDispatcher
Physics
Scene

The scene is the container for everything else in mutiny

Skinning
Time

Traits

Builder
Bundle
CreationContext