Crate rin::scene

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 new --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 entities.

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 as the basis of it’s ECS architecture so rinecs 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.

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.
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
immediate_renderer
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
physics	Physics systems and components in Mutiny, Right now mostly collisions
postprocessing	Postprocessing module including bloom, ssao, fxaa and tonemapping
render_stage
renderer	OpenGL renderer following the AZDO directives where available
scene	The Scene contains everything else.
skybox
time	Time utilities
transformation	Everything related to transformations in mutiny. From objects transformations to cameras
water

Macros

fragment_shader
fragment_shader_source
post_fragment
post_fragment_source
shader
shader_source
timed
vertex_shader
vertex_shader_source

Structs

BackgroundColor
Camera
CameraParts
CreationProxy
DeferredScene
EventsDispatcher
ImmediateRenderer
Physics
RenderWrapper
Scene	The scene is the container for everything else in mutiny
SceneBuilder	Creates a new scene from a renderer and an events dispatcher

Enums

RenderStage	The order of rendering is:
RendersTo

Constants

DEFAULT_EVENTS_PRIORITY

Traits

Builder
Bundle
CreationContext
EventsSystem
EventsSystemThreadLocal
RenderSystem
RendererBundle
UpdateSystem
UpdateSystemThreadLocal

Attribute Macros

render_system
update_system
update_system_thread_local

Derive Macros

Material