Tutorials

Creating a Window

The following code demonstrates the minimal setup required to create a window:

#include "engine.hpp"
#include "window.hpp"
 
int main(int, char**) {
  // Initialize the game engine, which sets up internal components.
  Engine engine;
 
  // Create a window
  Window window = Window::Make(engine, 640, 480, "ventana");
  
  // Enter the main loop to keep the window open.
  while (!window.isDone()) {}
  
  return 0;
}

Here, we create an Engine object. This class initializes internal components and serves as your gateway to the ResourceManager and the ComponentManager. Then, we need to create the Window where the scene will be displayed. Lastly, we loop to ensure the window is not automatically closed.

Drawing to the Window

---

In this section, we will explore the process of rendering objects to the window. To achieve this, we'll create a Renderer, set up a camera using the Entity-Component System (ECS), and visualize a simple red triangle.

Creating the Renderer

Creating the Renderer is pretty straightforward. Since we are not using lights, we will set the ambient light to 1 so that we display the real color of the object:

// Create a renderer with ambient light set to 1.0.
Renderer renderer = Renderer(engine, window, 1.0f);

Creating the Camera

To create a camera, we need to make use of the ComponentManager, which can be retrieved from the Engine. With that, we can create an entity with no parent, a TransformCmp, and a CameraCmp.

// Get the ComponentManager from the engine to manage entities and components.
ComponentManager& component_manager = engine.getComponentManager();
 
// Create a Camera entity with specified transformations.
component_manager.addEntity(
    nullptr,
    "Camera",
    TransformCmp(Vec3(0.0f, 0.0f, 5.0f), Vec3(0.0f), Vec3(1.0f)),
    CameraCmp(CameraProjection::kOrtho, Vec3::zero)
);

Components in depth

Creating the Triangle

We now need to create something to visualize. In this case, we will draw a red triangle. To do so, we will need an entity with a RenderCmp and a TransformCmp. But first, we will need to use the ResourceManager to get the mesh of the triangle.

// Get the ResourceManager from the engine to manage game assets.
ResourceManager& resource_manager = engine.getResourceManager();
 
// Create an entity with a RenderCmp, specifying a triangle mesh, no texture, and red color.
component_manager.addEntity(
    nullptr,
    "Triangle",
    TransformCmp(Vec3::zero, Vec3::zero, Vec3::unit),
    RenderCmp(
        &resource_manager.getMesh(BasicMesh::kTriangle),
        &resource_manager.getEmptyTexture(),
        Vec3(1.0f, 0.0f, 0.0f)
    )
);

One of the good things about ECS is that we now just need to call the system, and all the entities will be updated. So, we just need to call Renderer::render in the main loop, and our triangle should appear on the screen. Here is the complete code of the demo:

#include "window.hpp"
#include "ecs/component_manager.hpp"
#include "engine.hpp"
#include "renderer.hpp"
#include "resource_manager.hpp"
#include "globals.hpp"
using namespace coma;
int main(int, char**) {
  Engine engine;
  Window window = Window::Make(engine, 640, 480, "ventana");
  Renderer renderer = Renderer(engine, window, 1.0f);
 
  ComponentManager& component_manager = engine.getComponentManager();
  ResourceManager& resource_manager = engine.getResourceManager();
 
  component_manager.addEntity(
      nullptr,
      "Camera",
      TransformCmp(Vec3(0.0f, 0.0f, 5.0f), Vec3(0.0f), Vec3(1.0f)),
      CameraCmp(CameraProjection::kOrtho, Vec3::zero)
  );
 
  component_manager.addEntity(
      nullptr,
      "Triangle",
      TransformCmp(Vec3::zero, Vec3::zero, Vec3::unit),
      RenderCmp(
          &resource_manager.getMesh(BasicMesh::kTriangle),
          &resource_manager.getEmptyTexture(),
          Vec3(1.0f, 0.0f, 0.0f)
      )
  );
 
  while (!window.isDone()) {
    renderer.render();
  }
 
  return 0;
}

Loading Resources

---

Now, instead of using a red triangle, we are going to be loading our own meshes and textures.

For that, we will first need to get a mesh and a texture. You can use the ones that come with the demo project, but feel free to use the ones you like. Meshes must be in .obj format, and textures in .png or .jpg.

// Starts loading a mesh asynchronously
resource_manager.loadResource(
  ResourceType::kMesh,
  "../assets/obj/pollo.obj",
  "Shield"
);
 
// Starts loading a texture asynchronously
resource_manager.loadResource(
  ResourceType::kTexture,
  "../assets/textures/box.png",
  "Crate"
);
 
// Waits for all meshes to load
resource_manager.WaitResourceLoad();

When loading one or multiple assets, **WaitResourceLoad must be called once before using any of the loaded assets.**

To use the resource, we will replace the triangle we made in the previous code with a new entity:

component_manager.addEntity(
  nullptr,
  "Triangle",
  TransformCmp(Vec3::zero, Vec3::zero, Vec3::unit),
  RenderCmp(
    &resource_manager.getMesh("Shield"),
    &resource_manager.getTexture("Crate")
  )
);

Lastly, we will change our camera from ortho to perspective so that we can properly visualize the object.

Just with that, we should be able to see our mesh with the texture.

#include "window.hpp"
#include "ecs/component_manager.hpp"
#include "engine.hpp"
#include "renderer.hpp"
#include "resource_manager.hpp"
#include "globals.hpp"
using namespace coma;
int main(int, char**) {
  Engine engine;
  Window window = Window::Make(engine, 640, 480, "ventana");
  Renderer renderer = Renderer(engine, window, 1.0f);
 
  ComponentManager& component_manager = engine.getComponentManager();
  ResourceManager& resource_manager = engine.getResourceManager();
 
  resource_manager.loadResource(
    ResourceType::kMesh,
    "../assets/obj/sword_shield.obj",
    "Shield"
  );
  resource_manager.loadResource(
    ResourceType::kTexture,
    "../assets/texture/box.png",
    "Crate"
  );
  resource_manager.WaitResourceLoad();
 
  component_manager.addEntity(
    nullptr,
    "Camera",
    TransformCmp(Vec3(0.0f, 0.0f, 5.0f), Vec3(0.0f), Vec3(1.0f)),
    CameraCmp(CameraProjection::kPerspective, Vec3::zero)
  );
 
  component_manager.addEntity(
    nullptr,
    "Triangle",
    TransformCmp(Vec3::zero, Vec3::zero, Vec3::unit),
    RenderCmp(
      &resource_manager.getMesh("Shield"),
      &resource_manager.getTexture("Crate")
    )
  );
 
  while (!window.isDone()) {
    renderer.render();
  }
 
  return 0;
}

Adding Lights

---

Adding lights is pretty straightforward once you understand entities and components. The only thing we need is to create an entity with a LightCmp.

In our specific example, we will also need to modify the way we create the renderer because we have the ambient light set to one, so adding light will only add reflections.

Renderer renderer = Renderer(engine, window, 0.2f);
component_manager.addEntity(
  nullptr,
  "Point Light",
  TransformCmp(Vec3(2.0f, 3.0f, 3.0f)),
  LightCmp(Vec3::unit, 1.0f, 50.0f)
);

#include "window.hpp"
#include "ecs/component_manager.hpp"
#include "engine.hpp"
#include "renderer.hpp"
#include "resource_manager.hpp"
#include "globals.hpp"
using namespace coma;
int main(int, char**) {
  Engine engine;
  Window window = Window::Make(engine, 640, 480, "ventana");
  Renderer renderer = Renderer(engine, window, 0.2f);
 
  ComponentManager& component_manager = engine.getComponentManager();
  ResourceManager& resource_manager = engine.getResourceManager();
 
  resource_manager.loadResource(
    ResourceType::kMesh,
    "../assets/obj/sword_shield.obj",
    "Shield"
  );
  resource_manager.loadResource(
    ResourceType::kTexture,
    "../assets/texture/box.png",
    "Crate"
  );
  resource_manager.WaitResourceLoad();
 
  component_manager.addEntity(
    nullptr,
    "Camera",
    TransformCmp(Vec3(0.0f, 0.0f, 5.0f), Vec3(0.0f), Vec3(1.0f)),
    CameraCmp(CameraProjection::kPerspective, Vec3::zero)
  );
 
  component_manager.addEntity(
    nullptr,
    "Triangle",
    TransformCmp(Vec3::zero, Vec3::zero, Vec3::unit),
    RenderCmp(
      &resource_manager.getMesh("Shield"),
      &resource_manager.getTexture("Crate")
    )
  );
 
  component_manager.addEntity(
    nullptr,
    "Point Light",
    TransformCmp(Vec3(2.0f, 3.0f, 3.0f)),
    LightCmp(Vec3::unit, 1.0f, 50.0f)
  );
 
  while (!window.isDone()) {
    renderer.render();
  }
 
  return 0;
}

Input

---

To add input, the first thing is to define an InputButtonMap and create an InputMap with it. All the InputManager must be declared after the Renderer input wont work otherwise.

InputButtonMap g_input_map{
  {"Up",{InputButton::W,InputButton::UP}},
  {"Down",{InputButton::S,InputButton::DOWN}},
  {"Left",{InputButton::A,InputButton::LEFT}},
  {"Right",{InputButton::D,InputButton::RIGHT}},
};
 
InputManager input = InputManager(window, g_input_map);

Once we have that in the main loop, we can detect the input using the input manager we created:

if (input.buttonPressed("Up")) {
}
if (input.buttonPressed("Down")) {
}
if (input.buttonPressed("Left")) {
}
if (input.buttonPressed("Right")) {
}

But to actually update an entity with that, we will need to have its components. To retrieve them, we will first go to the creation of our shield entity and retrieve its value. and then cache its transform cmp:

Entity player = component_manager.addEntity(
  nullptr,
  "Shield",
  TransformCmp(Vec3::zero, Vec3::zero, Vec3::unit),
  RenderCmp(
    &resource_manager.getMesh("Shield"),
    &resource_manager.getTexture("Crate")
  )
);
 
TransformCmp* player_transform =
    component_manager.getComponent<TransformCmp>(player);

Now, in the main loop we had before, we can update the position of the component. We use Time::DeltaTime to get the time elapsed on the last frame and make the movement framerate independent. You can multiply it by any amount to adjust the movement speed:

if (input.buttonPressed("Up")) {
  player_transform->position.y += Time::DeltaTime();
}
if (input.buttonPressed("Down")) {
  player_transform->position.y -= Time::DeltaTime();
}
if (input.buttonPressed("Left")) {
  player_transform->position.x -= Time::DeltaTime();
}
if (input.buttonPressed("Right")) {
  player_transform->position.x += Time::DeltaTime();
}

Complete code:

#include "window.hpp"
#include "ecs/component_manager.hpp"
#include "engine.hpp"
#include "renderer.hpp"
#include "resource_manager.hpp"
#include "globals.hpp"
#include "Input.hpp"
#include "time.hpp"
 
using namespace coma;
InputButtonMap g_input_map{
  {"Up",{InputButton::W,InputButton::UP}},
  {"Down",{InputButton::S,InputButton::DOWN}},
  {"Left",{InputButton::A,InputButton::LEFT}},
  {"Right",{InputButton::D,InputButton::RIGHT}},
};
 
int main(int, char**) {
  Engine engine;
  Window window = Window::Make(engine, 640, 480, "ventana");
  Renderer renderer = Renderer(engine, window, 0.2f);
  InputManager input = InputManager(window, g_input_map);
  ComponentManager& component_manager = engine.getComponentManager();
  ResourceManager& resource_manager = engine.getResourceManager();
  
  resource_manager.loadResource(
    ResourceType::kMesh,
    "../assets/obj/sword_shield.obj",
    "Shield"
  );
  resource_manager.loadResource(
    ResourceType::kTexture,
    "../assets/texture/box.png",
    "Crate"
  );
  resource_manager.WaitResourceLoad();
 
  component_manager.addEntity(
    nullptr,
    "Camera",
    TransformCmp(Vec3(0.0f, 0.0f, 5.0f), Vec3(0.0f), Vec3(1.0f)),
    CameraCmp(CameraProjection::kPerspective, Vec3::zero)
  );
  Entity player = component_manager.addEntity(
    nullptr,
    "Shield",
    TransformCmp(Vec3::zero, Vec3::zero, Vec3::unit),
    RenderCmp(
      &resource_manager.getMesh("Shield"),
      &resource_manager.getTexture("Crate")
    )
  );
  component_manager.addEntity(
    nullptr,
    "Point Light",
    TransformCmp(Vec3(2.0f, 3.0f, 3.0f)),
    LightCmp(Vec3::unit, 1.0f, 50.0f)
  );
  TransformCmp* player_transform =
    component_manager.getComponent<TransformCmp>(player);
  
  while (!window.isDone()) {
    if (input.buttonPressed("Up")) {
      player_transform->position_.y += Time::DeltaTime();
    }
    if (input.buttonPressed("Down")) {
      player_transform->position_.y -= Time::DeltaTime();
    }
    if (input.buttonPressed("Left")) {
      player_transform->position_.x -= Time::DeltaTime();
    }
    if (input.buttonPressed("Right")) {
      player_transform->position_.x += Time::DeltaTime();
    }
    renderer.render();
  }
 
  return 0;
}

Custom Components and Systems

---

The result of this tutorial will be very similar to the last one, but it's important to learn how to create custom components and systems to unlock the full potential of the engine. Instead of updating the transform directly, we will create a MovementCmp that will hold a direction and a speed, and then we will use a system to update the transform based on the direction and speed stored in the component.

// Define component
struct MovementCmp {
  coma::Vec3 direction = Vec3::zero;
  float speed = 0;
};
 
// Define system
void MovementSystem(ComponentManager& component_manager) {
  auto& movement_list = component_manager.getComponentList<MovementCmp>();
  auto& transforms_list = component_manager.getSparseList<TransformCmp>();
 
  ComponentIterator iterator(movement_list, transforms_list);
  while (iterator.next()) {
    auto [move_cmp, transform_cmp] = iterator.get();
    transform_cmp.position_ +=
      move_cmp.direction * move_cmp.speed * Time::DeltaTime();
  }
}

With the component and system created, we first need to register the component in the component manager. Then, we will update our player entity to contain a MovementCmp, and instead of caching the TransformCmp, we will now cache this component.

// Register the component
component_manager.addComponentClass<MovementCmp>();
 
// Entity holding the new component
Entity player = component_manager.addEntity(
  nullptr,
  "Shield",
  TransformCmp(Vec3::zero, Vec3::zero, Vec3::unit),
  RenderCmp(
    &resource_manager.getMesh("Shield"),
    &resource_manager.getTexture("Crate")
  ),
  MovementCmp{Vec3::zero, 1.0f}
);
 
// Cache MovementCmp
MovementCmp* player_move =
  component_manager.getComponent<MovementCmp>(player);

Lastly, we will modify the main loop so that it uses the system.

player_move->direction = coma::Vec3::zero;
if (input.buttonPressed("Up")) {
  player_move->direction.y++;
}
if (input.buttonPressed("Down")) {
  player_move->direction.y--;
}
if (input.buttonPressed("Left")) {
  player_move->direction.x--;
}
if (input.buttonPressed("Right")) {
  player_move->direction.x++;
}
 
MovementSystem(component_manager);

complete code

#include "Input.hpp"
#include "ecs/component_manager.hpp"
#include "engine.hpp"
#include "globals.hpp"
#include "renderer.hpp"
#include "resource_manager.hpp"
#include "window.hpp"
#include "time.hpp"
#include "ecs/lists_iterator.hpp"
 
// input mappings
InputButtonMap g_input_map{
    {"Up", {InputButton::W, InputButton::UP}},
    {"Down", {InputButton::S, InputButton::DOWN}},
    {"Left", {InputButton::A, InputButton::LEFT}},
    {"Right", {InputButton::D, InputButton::RIGHT}},
};
 
// define component
struct MovementCmp {
  coma::Vec3 direction = coma::Vec3::zero;
  float speed = 0;
};
 
// custom system
void MovementSystem(ComponentManager& compoent_manager) {
  auto& movement_list = compoent_manager.getComponentList<MovementCmp>();
  auto& transforms_list = compoent_manager.getSparseList<TransformCmp>();
 
  ComponentIterator iterator(movement_list, transforms_list);
  while (iterator.next()) {
    auto [move_cmp, transform_cmp] = iterator.get();
    transform_cmp.position_ +=
        move_cmp.direction * move_cmp.speed * Time::DeltaTime();
  }
}
 
int main(int, char**) {
  //required engine initializations
  Engine engine;
  Window window = Window::Make(engine, 640, 480, "ventana");
  Renderer renderer = Renderer(engine, window, 0.2f);
  InputManager input = InputManager(window, g_input_map);
  ComponentManager& component_manager = engine.getComponentManager();
  ResourceManager& resource_manager = engine.getResourceManager();
 
  //register custom component
  component_manager.addComponentClass<MovementCmp>();
 
  //load external resources
  resource_manager.loadResource(ResourceType::kMesh,
                                "../assets/obj/sword_shield.obj", "Shield");
  resource_manager.loadResource(ResourceType::kTexture,
                                "../assets/texture/box.png", "Crate");
  resource_manager.WaitResourceLoad();
 
  //create camera
  component_manager.addEntity(
      nullptr, "Camera",
      TransformCmp(coma::Vec3(0.0f, 0.0f, 5.0f), coma::Vec3(0.0f), coma::Vec3(1.0f)),
      CameraCmp(CameraProjection::kPerspective));
  //create main object
  Entity player = component_manager.addEntity(
      nullptr, "Shiled", TransformCmp(coma::Vec3::zero, coma::Vec3::zero, coma::Vec3::unit),
      RenderCmp(&resource_manager.getMesh("Shield"),
                &resource_manager.getTexture("Crate")),
      MovementCmp{coma::Vec3::zero, 1.0f});
  //create light
  component_manager.addEntity(nullptr, "Point Light",
                              TransformCmp(coma::Vec3(2.0f, 3.0f, 3.0f)),
                              LightCmp(coma::Vec3::unit, 1.0f, 50.0f));
 
  //cache component
  auto* player_move = component_manager.getComponent<MovementCmp>(player);
 
  //main loop
  while (!window.isDone()) {
    //update input
    player_move->direction = coma::Vec3::zero;
    if (input.buttonPressed("Up")) {
      player_move->direction.y++;
    }
    if (input.buttonPressed("Down")) {
      player_move->direction.y--;
    }
    if (input.buttonPressed("Left")) {
      player_move->direction.x--;
    }
    if (input.buttonPressed("Right")) {
      player_move->direction.x++;
    }
 
    //update position
    MovementSystem(component_manager);
 
    //render scene
    renderer.render();
  }
 
  return 0;
}