Cosmic
C++20 OpenGL 2D Game & Simulation Engine
Cosmic is proven by what runs on top of it — from the canonical template that every project starts from, to a live telemetry dashboard for a real combat robot. Expand a project to read how it works.
TemplateProject is a root manager Layerthat owns a set of child “mode” layers and switches between them:
- TemplateRenderLayer — material + shader + camera demo (animated, time-driven).
- TemplateSpriteLayer — sprite-sheet + ECS demo.
- TemplateRenderBenchmarkLayer — instanced-rendering stress test.
- BallPhysicsSystem — a ParallelSystem example running ball physics across worker threads (the canonical parallel-pipeline demo).
- TemplateTelemetryLayer — wires all five telemetry subsystems together for ~20 simulated agents (record → export → replay → live charts → click-to-inspect).
It is the reference for time management, the composite-layer architecture, ECS integration, parallel physics, and telemetry — and it documents the “double-tick trap” pitfall.
View on GitHub ↗
A single Cosmic plugin layer that:
- Connects to an ESP32 microcontroller over a Bluetooth-SPP COM port using Cosmic::SerialPort.
- Parses framed, checksummed raw KISS telemetry packets tagged Right / Left (one ESP32 reads two drive ESCs on separate UARTs) and decodes them to engineering units on the PC (voltage, current, eRPM, motor RPM, wheel speed in mph, power) — so the conversion constants (motor pole pairs, gear ratio, wheel diameter, slip factor) can be tuned live in the UI without reflashing.
- Feeds both sides into the engine telemetry stack: DataRecorder → CSV + .bin export → DataPlayer replay.
- Overlays Right (red) vs Left (blue) for every channel in a live/replay dashboard, plus a single-side drill-down panel.
- Drives a differential-drive robot visual on a top-down Cartesian map (auto-scaling grid, origin marker, trail) by integrating pose from the two wheel speeds, so you can watch the robot translate and turn.
Fault tolerance:the two sides are fully independent — if one ESC’s telemetry wire dies, that side is flagged (error note + red wheel) and the app keeps running on the surviving side.
Extras: ships ESP32 firmware plus a simulator sketch that synthesizes realistic dual-ESC telemetry over Bluetooth so the whole pipeline can be demoed with no ESC or robot required.
View on GitHub ↗Cosmic is a C++20, OpenGL-backed 2D game and simulation engine for Windows, built around a hot-reloadable plugin model: the engine compiles once into an executable, and each project you build compiles into its own .dll that the engine loads at runtime — so you iterate on your project without ever recompiling the engine.
But it isn’t just a toy renderer. Cosmic blends two worlds: a 2D engine (batch renderer, entity-component-system, materials and shaders, cameras, a multithreaded job system) and a real-time instrumentation platform (a telemetry stack that records, exports and replays data; serial-port hardware I/O; and live ImPlot charts).
That telemetry-and-serial combination lets it talk to real hardware and visualize it live — an uncommon capability for a personal engine, and the reason it has a genuine real-world application: instrumenting a real combat robot.
Cosmic splits into two binaries. The engine host is a single .exe, compiled once. Each project is a separate client workspace — a .dll the host loads at runtime and can hot-reload without ever restarting.
Every project’s entry point is a single Layer subclass. You override only the hooks you care about — OnAttach, OnUpdate, OnFixedUpdate, OnImGuiRender, OnEvent— and export the layer from your DLL. The engine’s Launcherhas a New Project button that copies the canonical template, renames every file and class to your project, and generates a wired CMakeLists.txt and build.bat.
The engine is written from scratch in modern C++. These are its building blocks — the renderer, the ECS, the job system, and the telemetry stack that makes it a real-time data lab.
Telemetry System
Five subsystems working as one. DataRecorder captures per-entity float channels (thread-safe, multi-entity); DataPlayer replays the binary log with seek + interpolation; the TelemetryPanel owns the replay lifecycle with a scrubbable transport bar and live ImPlot charts; and EntitySelection + EntityPicker add click-to-inspect via a world-space hit test. It records to CSV and a binary .bin.
Serial Communication
A Windows COM-port reader (SerialPort) running on its own thread — used to ingest live telemetry from microcontrollers such as an ESP32 over Bluetooth-SPP. This is what connects the engine to real hardware.
Hot-Reloadable Plugin DLLs
The engine .exe loads project .dlls at runtime — rebuild and reload a project without ever restarting the engine.
Layer System
Clean lifecycle hooks — OnAttach, OnUpdate, OnFixedUpdate, OnImGuiRender, OnEvent — plus composite, multi-mode layer support.
2D Batch Renderer
Renderer2D batches quads, lines and SDF circles into minimal draw calls and tracks render stats such as draw-call counts.
Instanced Rendering
A stress-tested path for drawing huge numbers of objects efficiently; the template ships an instanced-rendering benchmark layer.
SDF Circles
Crisp, resolution-independent circles via signed-distance-field shading rather than triangulated geometry.
Materials & Shaders
A Material is a typed uniform bag; a custom GLSL preprocessing system and a documented “shader contract” govern standard uniforms like u_ViewProjection, u_Time and u_ViewportSize.
Sprite Sheets
SubTexture2D addresses atlas sub-regions, making sprite-sheet rendering straightforward.
Entity-Component-System
Scene owns an EnTT registry with built-in TransformComponent, SpriteRendererComponent and TagComponent. Systems come in serial (System) and parallel (ParallelSystem) flavors; rendering groups by material bucket and sorts by depth.
Job System & Parallel Pipeline
A persistent thread pool (worker count = logical cores − 1) with ParallelFor helpers, plus a four-pass pipeline and automatic snapshot/commit via SystemQuery<T> so per-entity simulation runs safely across all cores.
Time & Timeline System
A global time-scale plus per-layer time-scales cascade through the update hooks — supporting pause, rewind (negative time scale) and a fixed-timestep pass for deterministic physics.
Camera System
An orthographic camera paired with a WASD + scroll-zoom controller.
Virtual File System
Path resolution with engine:// and project:// prefixes so assets and logs resolve correctly per project.
Framebuffer (FBO)
Render the scene to an offscreen texture so it can be composited inside an ImGui viewport panel.
Logging
CS_INFO / CS_WARN / CS_ERROR macros (spdlog); the log directory can be redirected into a project’s own asset folder.
#include <Cosmic.h>
class MyProject : public Cosmic::Layer
{
public:
MyProject() : Cosmic::Layer("MyProject") {}
void OnAttach() override { /* create GPU resources, scene, systems */ }
void OnUpdate(float ts) override { /* per-frame logic + rendering */ }
void OnFixedUpdate(float dt) override { /* fixed-step physics */ }
void OnImGuiRender() override { /* draw ImGui/ImPlot panels */ }
void OnEvent(Cosmic::Event& e) override { /* handle input/window events */ }
void OnDetach() override { /* release resources */ }
};A minimal Cosmic project is a single Layer.
Parallel ECS systems run through a structured four-pass pipeline. Components are snapshotted up front, per-entity work fans out across the worker pool, and results are committed back on a single thread — so simulation scales across cores without data races.
| Script | Use |
|---|---|
| setup.bat | Run once per machine. Registers the COSMIC_SDK_DIR env var that every project’s CMake relies on. |
| build_all.bat | Full CMake reconfigure + compile of the engine and all projects. Use after cloning or adding a project. |
| build.bat | Incremental build — skips CMake reconfigure. Day-to-day iteration. |
| build_engine.bat | Builds only the engine host. |
| build_all_release.bat | Clean Release build for distribution. |
/O2 with no asserts (for distribution and benchmarking). The rule: never benchmark in Debug — it can be 5–10× slower. Outputs land in build/Runtime/Debug/ or build/Runtime/Release/.Note: the README in this GitHub repository goes significantly deeper than this page.