Arquitectura del Motor y Estructura
Targets CMake y Módulos
Organización del motor, dependencias embebidas y pipeline de compilación.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áticaContiene la totalidad de los subsistemas del motor: renderizado PBR, simulador físico SAT, grafo de escena ECS, scripting, audio y telemetría.
Mei (Editor)
EjecutableEntorno visual interactivo basado en Dear ImGui (docking), con gizmos 3D, consola, profiler en vivo, navegador de assets y launcher.
MeiTests
Suite de PruebasSuite integral con 147 pruebas unitarias automatizadas en GoogleTest, con soporte para contexto OpenGL Headless y verificación pre-commit.
# 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.
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.- Cero asignaciones dinámicas en el bucle principal: Está estrictamente prohibido usar
new,malloco redimensionar vectores (std::vector::push_backque provoque reallocation) en los bucles de física (PhysicsSystem::Update), renderizado (Scene::Draw) o telemetría (Profiler). - Caché de consultas: Operaciones como
GetComponent<T>()yGetGlobalMatrix()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 idauto-incrementable determinista. Nunca se deben usar punteros en crudo para hashing o indexación persistente.
Sistema de Scripting Nativo en C++20
Mei::ScriptComponent
Clase base polimórfica recomendada para toda la lógica de juego nativa en C++.
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. |
#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.
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.
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.
Grafo de Escena y Componentes (ECS)
Mei::GameObject
Entidad base contenedora del grafo de transformación y componentes polimórficos.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
// 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.| 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.// 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.
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). |
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.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.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.| 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.
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.
Pipeline de Renderizado PBR & Shaders
Mei::MeshComponent
Renderizador de geometría 3D con iluminación PBR (Cook-Torrance / GGX) y Shaders a medida.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.
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.
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 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.
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)$.
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.
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.
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
Sistema de Audio Espacial 3D
Mei::AudioManager & AudioSourceComponent
Motor de sonido de baja latencia con atenuación por distancia y posicionamiento espacial.
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.
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();
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.
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.
void CustomSystem::Execute() { MEI_PROFILE_SCOPE(Mei::ProfileCategory::Scripts); // Algoritmo intensivo medido automáticamente sin allocar memoria ProcessComplexPathfinding(); }
Subsistemas Core y Utilidades
Mei::Time & Mei::Input
Gestión de tiempos, escalas y eventos de periféricos de entrada.// 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.
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.