VOLO.LAT TECH C++20 ENGINE OPENGL 4.6

Mei.engine

Referencia técnica completa y manual de API en C++20: ECS tipo Unity, pipeline de renderizado PBR, sombras suaves PCF, física SAT 3D, partículas zero-allocation, audio espacial 3D y telemetría de rendimiento en tiempo real.

0 Allocations Hot Path Físico y Profiler
16-Tap PCF Sombras Suaves Poisson Disk
1% Lows Detección de Stuttering
VOLO.LAT TECH C++20 ENGINE OPENGL 4.6
Total: 40+ símbolos documentados
Módulo 1

Arquitectura del Motor y Estructura

Targets CMake y Módulos

Organización del motor, dependencias embebidas y pipeline de compilación.
C++20

Mei Engine está construido en C++20 moderno y OpenGL 4.6 Core Profile, estructurado en tres targets principales de CMake para máxima modularidad y desacoplamiento:

MeiCore

Librería Estática

Contiene la totalidad de los subsistemas del motor: renderizado PBR, simulador físico SAT, grafo de escena ECS, scripting, audio y telemetría.

Mei (Editor)

Ejecutable

Entorno visual interactivo basado en Dear ImGui (docking), con gizmos 3D, consola, profiler en vivo, navegador de assets y launcher.

MeiTests

Suite de Pruebas

Suite integral con 147 pruebas unitarias automatizadas en GoogleTest, con soporte para contexto OpenGL Headless y verificación pre-commit.

Comandos de Compilación y Ejecución
# 1. Configurar proyecto CMake con soporte C++20
cmake -B build

# 2. Compilar motor y editor en modo Debug o Release
cmake --build ./build --config Debug

# 3. Ejecutar la suite completa de 147 pruebas unitarias
./build/tests/Debug/MeiTests.exe

Ciclo de Vida Seguro y Diferido

Prevención de invalidación de punteros durante la simulación física y de renderizado.
CRÍTICO

Durante la ejecución del juego (isPlaying == true), nunca se debe mutar directamente la colección gameObjects. Para garantizar la seguridad de memoria, Mei Engine implementa un sistema de Command Buffer diferido que ejecuta instanciaciones y destrucciones al término del frame:

Destrucción Segura: Destroy(obj, delay)

Encola la entidad para ser retirada al término del frame. Admite un tiempo opcional de retardo (delay en segundos) sin necesidad de corrutinas complejas.

Instanciación Segura: Instantiate(...)

Clona un GameObject o plantilla con sus componentes, lo sitúa en la posición/rotación deseadas e invoca su método Start() automáticamente.

Reglas de Rendimiento: Hot Path y Zero-Allocation

Estándares para bucles de 60/144 FPS estables sin pausas de recolección ni fragmentación de memoria.
ZERO-ALLOC
  • Cero asignaciones dinámicas en el bucle principal: Está estrictamente prohibido usar new, malloc o redimensionar vectores (std::vector::push_back que provoque reallocation) en los bucles de física (PhysicsSystem::Update), renderizado (Scene::Draw) o telemetría (Profiler).
  • Caché de consultas: Operaciones como GetComponent<T>() y GetGlobalMatrix() involucran casts dinámicos y multiplicaciones jerárquicas; deben cachearse en variables miembro si se acceden repetidamente en el mismo frame.
  • Identificadores únicos enteros: Cada entidad posee un identificador uint32_t id auto-incrementable determinista. Nunca se deben usar punteros en crudo para hashing o indexación persistente.
Módulo 2

Sistema de Scripting Nativo en C++20

Mei::ScriptComponent

Clase base polimórfica recomendada para toda la lógica de juego nativa en C++.
Header: <Mei/scene/ScriptComponent.h>
class ScriptComponent : public Component;

Heredar de Mei::ScriptComponent otorga acceso directo e inmediato a la entidad dueña (GetTransform(), GetScene()), ciclo de vida unificado, eventos físicos de colisión y triggers, así como compatibilidad completa con el sistema de reflexión para el Inspector del Editor.

Métodos Virtuales del Ciclo de Vida

Método Momento de Ejecución Propósito / Recomendación
void Awake() Instanciación en memoria Inicializar variables internas que no dependan de otros GameObjects.
void Start() Primer frame de Play Mode Configurar referencias a otros componentes, registrar oyentes y preparar estado inicial.
void Update(float deltaTime) Cada frame (Play Mode) Lógica principal, lectura de Input, movimiento y temporizadores. deltaTime está escalado por Time::timeScale.
void LateUpdate(float deltaTime) Tras finalizar todos los Update() Ideal para cámaras de seguimiento orbital o cinemáticas dependientes de la posición del jugador.
void OnDestroy() Inmediatamente antes de ser destruido Liberar recursos externos, desuscribir eventos y notificar a otros sistemas.

Callbacks de Físicas y Triggers

Callback Parámetro Descripción
OnCollisionEnter(GameObject* other) GameObject* Se dispara en el primer frame en que dos colliders físicos colisionan.
OnCollisionStay(GameObject* other) GameObject* Se ejecuta continuamente mientras persista el contacto físico entre entidades.
OnCollisionExit(GameObject* other) GameObject* Se activa en el frame en que los colliders se separan.
OnTriggerEnter(GameObject* other) GameObject* Se dispara cuando un collider físico ingresa a una zona fantasma (isTrigger = true).
OnTriggerExit(GameObject* other) GameObject* Se dispara cuando la entidad abandona el volumen trigger.
Ejemplo: Controlador de Personaje con Raycasting y MEI_FIELD
#include <Mei/scene/ScriptComponent.h>
#include <Mei/scene/ScriptProperty.h>
#include <Mei/core/Input.h>
#include <Mei/physics/Physics.h>

class PlayerController : public Mei::ScriptComponent {
public:
    MEI_FIELD(float, moveSpeed, 8.5f);
    MEI_FIELD(float, jumpForce, 12.0f);
    MEI_FIELD(int, maxHealth, 100);

    void Start() override {
        Mei::Console::Info("[PlayerController] Jugador listo con salud: " + std::to_string(maxHealth));
    }

    void Update(float deltaTime) override {
        glm::vec3 move(0.0f);
        if (Mei::Input::GetKey(GLFW_KEY_W)) move += GetTransform().forward();
        if (Mei::Input::GetKey(GLFW_KEY_S)) move -= GetTransform().forward();
        if (Mei::Input::GetKey(GLFW_KEY_D)) move += GetTransform().right();
        if (Mei::Input::GetKey(GLFW_KEY_A)) move -= GetTransform().right();

        if (glm::length(move) > 0.001f) {
            GetTransform().Translate(glm::normalize(move) * moveSpeed * deltaTime, false);
        }

        // Raycast al suelo para comprobar si está apoyado
        Mei::RaycastHit hit;
        bool isGrounded = Mei::Physics::Raycast(GetTransform().position, glm::vec3(0, -1, 0), 1.1f, hit);

        if (isGrounded && Mei::Input::GetKeyDown(GLFW_KEY_SPACE)) {
            auto rb = GetComponent<Mei::RigidBodyComponent>();
            if (rb) rb->AddImpulse(glm::vec3(0, jumpForce, 0));
        }
    }

    void OnCollisionEnter(Mei::GameObject* other) override {
        Mei::Console::Warn("Impacto con objeto: " + other->name);
    }
};

Macro MEI_FIELD y Reflexión

Exposición interactiva de variables al Inspector del Editor y serialización en archivos .mei.
MACRO
MEI_FIELD(Type, Name, DefaultValue);

Permite a los diseñadores y programadores modificar variables numéricas, booleanas, cadenas y vectores en tiempo real desde la ventana del Inspector del Editor sin recompilar el código. Además, el motor se encarga de serializar y deserializar estos campos automáticamente en el archivo de escena .mei.

Tipos Soportados Control Renderizado en ImGui Ejemplo de Uso
float, double DragFloat con step configurable MEI_FIELD(float, speed, 5.0f);
int DragInt MEI_FIELD(int, ammoCount, 30);
bool Checkbox interactivo MEI_FIELD(bool, isInvincible, false);
std::string InputText MEI_FIELD(std::string, heroName, "Kael");
glm::vec3 DragFloat3 con badges X, Y, Z MEI_FIELD(glm::vec3, spawnOffset, glm::vec3(0, 1, 0));

ScriptRegistry & ScriptHotReloader

Instanciación dinámica por nombre y recarga de scripts C++ en caliente mediante DLLs.
DLL HOT-RELOAD
template<typename T> void ScriptRegistry::Register(const std::string& className);

Mei Engine cuenta con un sistema de compilación y recarga en caliente de scripts (ScriptHotReloader). Cuando el desarrollador modifica un script en la carpeta del proyecto, el motor compila una DLL temporal, preserva los valores de las variables reflejadas mediante MEI_FIELD, descarga la DLL anterior e inyecta la nueva instancia en memoria sin cerrar el editor.

Módulo 3

Grafo de Escena y Componentes (ECS)

Mei::GameObject

Entidad base contenedora del grafo de transformación y componentes polimórficos.
Header: <Mei/scene/GameObject.h>
class GameObject : public std::enable_shared_from_this<GameObject>;

Propiedades Principales

Propiedad Tipo Descripción
id uint32_t Identificador único inmutable auto-incrementable de la entidad.
name std::string Nombre descriptivo visualizado en la jerarquía del editor.
transform Transform Transformación espacial local de posición, rotación Euler y escala.
parent GameObject* Puntero no-owner al padre en la jerarquía (nullptr si es raíz).
children std::vector<std::shared_ptr<GameObject>> Lista de hijos cuya transformación espacial hereda de esta entidad.
visible / active bool Flags que controlan la visibilidad en renderizado y la actualización de lógica.

Métodos de Gestión de Componentes

Sintaxis de Gestión de Componentes en GameObject
// 1. Añadir componente pasando parámetros a su constructor
auto meshComp = obj->AddComponent<Mei::MeshComponent>(meshPtr, shaderPtr);

// 2. Obtener el primer componente de un tipo dado (dynamic_pointer_cast interno)
auto rb = obj->GetComponent<Mei::RigidBodyComponent>();
if (rb) {
    rb->mass = 5.0f;
}

// 3. Obtener colección de componentes múltiples (ej. scripts o capas de textura)
auto scripts = obj->GetComponents<Mei::ScriptComponent>();

// 4. Obtener matriz de transformación global en el mundo
glm::mat4 worldMatrix = obj->GetGlobalMatrix();

Mei::Transform

Coordenadas locales, vectores direccionales y matrices de proyección espacial.
Header: <Mei/scene/Transform.h>
class Transform;
Método / Miembro Retorno Propósito
position, rotation, scale glm::vec3 Posición local, rotación Euler (en grados sexagesimales) y factor de escala.
forward() glm::vec3 Vector normalizado hacia el frente de la entidad (-Z en OpenGL).
right() glm::vec3 Vector normalizado hacia la derecha de la entidad (+X).
up() glm::vec3 Vector normalizado hacia arriba de la entidad (+Y).
Translate(offset, local) void Desplaza la posición local o según el sistema de coordenadas local del objeto.
GetLocalMatrix() glm::mat4 Calcula la matriz $T \times R \times S$ local en base a los miembros actuales.

Mei::Scene

Contenedor del mundo, simulación de Play Mode con snapshots en RAM y serialización.
Header: <Mei/scene/Scene.h>
class Scene;
Control de Play Mode y Snapshot en RAM
// Iniciar simulación de juego: toma snapshot en memoria RAM sin tocar disco
scene->StartPlayMode();

// Pausar / reanudar simulación
scene->TogglePausePlayMode();

// Avanzar exactamente 1 frame (1/60s) en estado pausado para debugging físico
scene->StepFrame();

// Detener simulación: restaura el estado exacto de las entidades previo a Play
scene->StopPlayMode();

Mei::EnvironmentSettings

Configuración atmosférica global: Skybox procedural, cubemaps, niebla volumétrica y fondo.
Header: <Mei/scene/Scene.h>

Controla el entorno lumínico y atmosférico que rodea a la escena, persistido automáticamente en los archivos de proyecto .mei.

Propiedad Tipo Descripción
skyboxMode SkyboxMode SolidColor (0), Procedural (1) o Cubemap (2).
zenithColor / horizonColor / groundColor glm::vec3 Colores del gradiente atmosférico para cielo procedural en coordenadas esféricas.
sunColor / sunDiskSize glm::vec3 / float Color e intensidad del disco solar dinámico vinculado a la luz direccional principal.
cubemapFaces std::array<std::string, 6> Rutas a las 6 texturas en orden $+X, -X, +Y, -Y, +Z, -Z$.
fogEnabled / fogMode bool / int Habilitación de niebla (0 = Lineal por distancia, 1 = Exponencial con caída por altura).
Módulo 4

Motor de Físicas 3D y Colisiones (SAT)

Mei::PhysicsSystem

Simulador físico de cuerpos rígidos basado en impulsos, SAT, contact caching y warm starting.
ZERO-ALLOC

El motor de física de Mei implementa el Teorema de los Ejes Separadores (SAT) para la detección precisa de colisiones entre cajas orientadas (OBB), esferas y cápsulas. Para eliminar el temblor (*jittering*) y lograr un apilamiento estable de objetos (*stacking*), utiliza Contact Caching con Warm Starting (conservación de impulsos normales y de fricción entre frames consecutivos) junto con un Sleep System que duerme cuerpos estables.

Warm Starting & Fricción

Almacena impulsos acumulados por contacto para aplicarlos como estimación inicial en la siguiente iteración del solver, reduciendo el error y la oscilación a 0.

Sistema de Reposo (Sleep)

Desactiva el cómputo de entidades cuya energía cinética sea inferior al umbral mínimo durante 0.5s, reactivándolas instantáneamente ante un choque o impulso externo.

Mei::Physics::Raycast

Lanzamiento estático de rayos contra colliders de la escena con información de impacto.
Static Facade
static bool Physics::Raycast(const glm::vec3& origin, const glm::vec3& direction, float maxDistance, RaycastHit& hitInfo, int layerMask = -1);
Ejemplo de Detección de Disparo por Raycast
Mei::RaycastHit hit;
glm::vec3 rayOrigin = camera.Position;
glm::vec3 rayDir = camera.Orientation;

if (Mei::Physics::Raycast(rayOrigin, rayDir, 100.0f, hit)) {
    Mei::Console::Info("Impacto en: " + hit.gameObject->name + " a distancia: " + std::to_string(hit.distance));
    
    // Aplicar impulso de impacto si el objeto tiene física
    auto rb = hit.gameObject->GetComponent<Mei::RigidBodyComponent>();
    if (rb) {
        rb->AddImpulse(rayDir * 25.0f);
    }
}

Mei::RigidBodyComponent

Componente de dinámica de cuerpo rígido con fuerzas, gravedad y restricciones angulares.
Component
Propiedad / Método Tipo Descripción
mass / inverseMass float Masa en kilogramos. Si se marca isKinematic = true, la masa inversa pasa a 0.
velocity / angularVelocity glm::vec3 Vectores de velocidad lineal y velocidad angular en radianes por segundo.
useGravity / isKinematic bool Indica si aplica la aceleración de gravedad (-9.81 m/s²) y si es controlado por scripts sin responder a impulsos.
freezeRotationX / Y / Z bool Bloquea los ejes de rotación específicos para avatares y personajes que deban mantenerse verticales.
AddForce(force) void Aplica una fuerza continua acumulada para el siguiente paso de integración.
AddImpulse(impulse) void Aplica un cambio instantáneo de momento lineal ($\Delta v = J / m$).

Mei::CharacterControllerComponent

Controlador cinemático de personajes con superación de escalones y pendientes.
Component
void CharacterControllerComponent::Move(const glm::vec3& displacement, float deltaTime);

Diseñado para avatares de jugadores y NPCs en tercera y primera persona. Evita el comportamiento inestable de los cuerpos rígidos tradicionales, permitiendo deslizarse por pendientes hasta slopeLimit grados, superar bordes y escalones mediante stepOffset y detectar de forma determinista el suelo mediante isGrounded.

Módulo 5

Pipeline de Renderizado PBR & Shaders

Mei::MeshComponent

Renderizador de geometría 3D con iluminación PBR (Cook-Torrance / GGX) y Shaders a medida.
Component

Controla la visualización del modelo tridimensional, admitiendo tanto el shader base de iluminación física (PBR) con mapas de albedo, normales, rugosidad y metalicidad, como la inyección de shaders GLSL totalmente personalizados escritos por el desarrollador.

Asignación de Shaders Personalizados en C++
auto meshComp = obj->GetComponent<Mei::MeshComponent>();
if (meshComp) {
    // Carga y compila un shader GLSL a medida para efectos de agua, disolución o hologramas
    meshComp->SetCustomShader("assets/shaders/water.vert", "assets/shaders/water.frag");
}

Sombras Suaves PCF (Poisson Disk 16 Muestras)

Filtrado anti-aliasing de penumbra en bordes con sesgo adaptativo a la pendiente.
GLSL KERNEL

El shader default.frag implementa un kernel de filtrado Percentage-Closer Filtering (PCF) distribuido en un disco de Poisson de 16 muestras. Además, incorpora un sesgo adaptativo (slope-scale bias) calculado dinámicamente según la normal y la dirección de la luz:

float cosTheta = clamp(dot(normal, lightDir), 0.0, 1.0);
float bias = clamp(0.005 * sqrt(1.0 - cosTheta * cosTheta) / max(cosTheta, 0.001), 0.0005, 0.015);

Skybox 360° & Reflejos Ambientales IBL

Cielo procedural dinámico alineado con el sol, soporte Cubemap y reflejos IBL en PBR.
Header: <Mei/render/Skybox.h>

El componente Skybox proyecta un cubo unitario en el plano lejano ($z/w = 1.0$) anulando la traslación de la cámara. Los materiales con reflectancia (u_reflectance > 0) o metales reflejan el cielo circundante en tiempo real mediante el vector $R = \text{reflect}(I, N)$.

Módulo 6

Sistema de Partículas 3D Zero-Allocation

Mei::ParticleSystemComponent

Emisor de partículas 3D con billboards orientados a la cámara y memoria estática pre-asignada.
POOL ESTÁTICO

Diseñado para efectos de fuego, humo, chispas y polvo. Utiliza un pool circular de tamaño fijo pre-asignado en memoria (maxParticles = 500) sin realizar un solo malloc en runtime. Los cuads se orientan automáticamente hacia la cámara en el shader de billboard.

Creación de Efecto de Fuego con Partículas
auto fire = obj->AddComponent<Mei::ParticleSystemComponent>();
fire->emissionRate = 60.0f;           // 60 partículas por segundo
fire->startLifetime = 1.2f;          // Vida de cada partícula
fire->startSpeed = 2.5f;             // Velocidad de ascenso
fire->startSize = 0.6f;              // Tamaño inicial
fire->endSize = 0.1f;                // Reducción al disiparse
fire->startColor = glm::vec4(1.0f, 0.7f, 0.1f, 1.0f); // Amarillo fuego
fire->endColor = glm::vec4(0.8f, 0.1f, 0.0f, 0.0f);   // Rojo transparente
fire->emitterShape = Mei::ParticleEmitterShape::Cone;
fire->gravityMultiplier = -0.5f;     // Flotabilidad ascendente
Módulo 7

Sistema de Audio Espacial 3D

Mei::AudioManager & AudioSourceComponent

Motor de sonido de baja latencia con atenuación por distancia y posicionamiento espacial.
miniaudio

Implementado sobre miniaudio para reproducción de efectos de sonido y música en formatos WAV, MP3 y FLAC. El componente AudioSourceComponent admite atenuación logarítmica/lineal por distancia (minDistance, maxDistance) y paneo 3D en relación a la posición del AudioListenerComponent.

Reproducción de Sonido 3D en C++
auto audio = obj->AddComponent<Mei::AudioSourceComponent>();
audio->audioClipPath = "assets/sounds/explosion.wav";
audio->spatial3D = true;
audio->minDistance = 2.0f;
audio->maxDistance = 45.0f;
audio->Play();
Módulo 8

Telemetría de Rendimiento & Profiler

Mei::Profiler & MEI_PROFILE_SCOPE

Medición de microsegundos, ring buffer de 120 frames y cálculo de 1% lows.
HIGH-RES TELEMETRY
MEI_PROFILE_SCOPE(Mei::ProfileCategory::Render);

Permite medir con precisión estricta de nanosegundos (std::chrono::high_resolution_clock) cualquier bloque de código mediante temporizadores RAII. La telemetría se acumula en un ring buffer estático circular de 120 frames, calculando en tiempo real:

  • FPS Promedio / Mínimo / Máximo.
  • 1% Low FPS (percentil 99 del tiempo de frame para detección analítica de micro-tirones).
  • 0.1% Low FPS (percentil 99.9 para caídas severas de fluidez).
  • Métricas de primitivas GPU: Draw calls, state changes, triángulos dibujados y entidades descartadas por Frustum Culling.
Instrumentación de una Tarea Pesada con MEI_PROFILE_SCOPE
void CustomSystem::Execute() {
    MEI_PROFILE_SCOPE(Mei::ProfileCategory::Scripts);
    
    // Algoritmo intensivo medido automáticamente sin allocar memoria
    ProcessComplexPathfinding();
}
Módulo 9

Subsistemas Core y Utilidades

Mei::Time & Mei::Input

Gestión de tiempos, escalas y eventos de periféricos de entrada.
Core
Uso de Input y Time en Gameplay
// Tiempo escalado transcurrido
float dt = Mei::Time::deltaTime;
float totalTime = Mei::Time::time;

// Modificar escala temporal (ej. cámara lenta)
Mei::Time::timeScale = 0.5f;

// Entrada de teclado
if (Mei::Input::GetKeyDown(GLFW_KEY_E)) {
    InteractWithEntity();
}

// Entrada de ratón
if (Mei::Input::GetMouseButton(GLFW_MOUSE_BUTTON_LEFT)) {
    auto mousePos = Mei::Input::GetMousePosition();
}

Mei::AssetPacker (.meipack)

Empaquetado binario comprimido de escenas y assets para distribución de proyectos.
Binary Archive

Permite agrupar modelos 3D (.obj, .fbx), texturas, shaders, clips de audio y archivos de escena .mei en un único archivo binario .meipack protegido con cabecera de integridad para distribución en producción y cargas seguras en runtime.