{
  "markdown": "# MistEngine 0.5.0\n\n[![Version](https://img.shields.io/badge/version-0.5.0--prealpha-brightgreen.svg)](https://github.com/aayushmishraaa/MistEngine)\n[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20Windows-blue.svg)](https://github.com/aayushmishraaa/MistEngine)\n[![C++](https://img.shields.io/badge/C%2B%2B-17-blue.svg)](https://github.com/aayushmishraaa/MistEngine)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\n> A C++17 OpenGL 4.6 engine — editor and renderer sandbox.\n\nMistEngine is a 3D engine built around an Entity-Component-System core, a PBR forward renderer with\ncascaded shadow maps and a screen-space post-process chain, Bullet physics, a Dear ImGui editor with\ndockable panels and transform gizmos, Lua scripting via sol2, and hot-loadable plugin modules. It\nbuilds from one CMake tree on Linux and Windows.\n\n**Pre-alpha.** This is a working sandbox, not a shipping engine. See\n[Known limitations](#known-limitations) before starting anything that depends on it.\n\n---\n\n## Platform support\n\n| Platform | Builds | Tests | Editor runs |\n|---|---|---|---|\n| Linux (x86_64) | yes | yes | yes |\n| Windows (x64, vcpkg) | yes | yes | yes |\n| macOS (Apple Silicon / Intel) | yes | yes | **no** |\n\nmacOS builds the library and runs the full headless test suite, but **cannot run the editor**.\nApple's OpenGL implementation is deprecated and frozen at 4.1, while the renderer depends on\nOpenGL 4.3–4.6 features throughout: direct-state-access entry points (~220 call sites), compute\nshaders (clustered light culling, Hi-Z reduction, SSR, GPU particles), shader storage buffers, image\nload/store, and `#version 460 core` in all 51 shaders. Supporting it would mean a second,\nGL 4.1-compatible backend — or a Vulkan backend behind `RenderingDevice` running on MoltenVK. Neither\nexists yet. Develop the renderer on Linux or Windows; use the macOS preset for tests.\n\n---\n\n## Building\n\n### Dependencies\n\nOpenGL, GLFW 3, GLM, Assimp, Bullet 3, Freetype. Fetched automatically via CMake `FetchContent`:\nDear ImGui (docking branch), ImGuizmo, nlohmann/json, Lua 5.4, sol2, Catch2. Every dependency is\npinned to an exact tag or SHA.\n\n```bash\n# Linux\nsudo apt-get install ninja-build libglfw3-dev libglm-dev libassimp-dev \\\n                     libbullet-dev libfreetype-dev\ncmake --preset linux-release && cmake --build --preset linux-release -j\n./build-linux-release/MistEngine\n\n# macOS (library + tests only)\nbrew install cmake ninja glfw glm assimp bullet freetype\ncmake --preset mac-debug && cmake --build --preset mac-debug -j\nctest --preset mac-debug --output-on-failure\n\n# Windows (needs VCPKG_ROOT)\ncmake --preset windows-release && cmake --build --preset windows-release --config Release\n```\n\n### Presets\n\n| Preset | Notes |\n|---|---|\n| `linux-debug` | Debug + AddressSanitizer + UBSan |\n| `linux-release` | Optimised |\n| `linux-ci` | Debug, no sanitizers — what CI runs |\n| `linux-runtime` | `MIST_BUILD_EDITOR=OFF`, headless runtime |\n| `mac-debug` | Library + tests; editor will not run |\n| `windows-release` | Visual Studio 17 2022, vcpkg toolchain |\n\n### Options\n\n`MIST_BUILD_EDITOR` (ON) · `MIST_ENABLE_SCRIPTING` (ON) · `MIST_ENABLE_TESTS` (ON) ·\n`MIST_ENABLE_AUDIO` (OFF) · `MIST_ASAN` (OFF) · `MIST_TEST_GL` (OFF)\n\nRun the test suite with `ctest --preset <preset>`. It is headless by design — no window, no GL\ncontext, no network.\n\n---\n\n## What's actually in here\n\n### Rendering\n\n- Forward PBR (Cook-Torrance GGX), HDR pipeline, AgX / ACES / Reinhard tonemapping\n- Cascaded shadow maps — 4 cascades at 2048², PCSS soft shadows with separated blocker bias\n- Omni shadows — cubemap array, up to 4 shadow-casting point lights\n- Clustered lighting — 16×9×24 grid, compute-shader culling, 1024-light SSBO\n- Post-process chain: bloom, SSAO, TAA (Halton jitter + variance clipping), SSR over a Hi-Z\n  pyramid, bokeh depth of field, motion blur, FXAA\n- Depth prepass writing octahedral-packed normals and roughness\n- Procedural and atmospheric skyboxes\n\n### Engine\n\n- ECS with signature-based system matching and a flat scene-graph component\n- Bullet physics with RAII ownership wrappers, fixed 60 Hz timestep, shape-hash body rebuild\n- Lua scripting (sol2) with per-script sandboxed environments — spawn, transform, physics, lighting,\n  animation and raycast bindings\n- Reflection (`MIST_REFLECT`) driving the Inspector, scene JSON and `.mistmat` materials from one\n  declaration\n- Assimp scene import (`.obj` / `.fbx` / `.gltf` / `.glb`) with PBR texture resolution\n- `.mist` scene format and `.mistpkg` single-file archives\n- Hot-loadable plugin modules (`.so` / `.dll` / `.dylib`) behind a sandboxed loader\n\n### Editor\n\n- Dockable ImGui layout with persisted arrangement, three themes\n- Hierarchy with drag-drop reparenting, reflection-driven Inspector, asset browser\n- ImGuizmo translate/rotate/scale handles with snapping\n- Undo/redo with Godot-style merge semantics (slider drags collapse to one step)\n- Console doubling as a Lua REPL\n- Profiler with non-blocking GPU timer queries\n\n---\n\n## Controls\n\n| Key | Action |\n|---|---|\n| `WASD` / `QE` | Fly camera |\n| Right-drag | Mouse look |\n| Middle-drag | Orbit · `Shift` + middle-drag to pan |\n| Scroll | Zoom |\n| `Numpad 1/3/7` | Front / right / top view |\n| `Numpad 5` | Toggle orbit mode · `Numpad 0` resets |\n| `F` | Focus selection |\n| `W` / `E` / `R` | Translate / rotate / scale gizmo |\n| `Ctrl+Z` / `Ctrl+Y` | Undo / redo |\n| `F1` | ImGui demo window |\n| `Esc` | Quit |\n\n---\n\n## Known limitations\n\nHonest list, because several of these look like they work:\n\n- **Skeletal animation renders a static bind pose.** Rigs import and clips populate the Inspector,\n  but the bone hierarchy walk is unimplemented and the inverse bind matrix is never applied.\n- **Image-based lighting is not wired up.** `IBL::ProcessEnvironmentMap` has no caller and its\n  cubemap convolution draws without a bound VAO. Ambient falls back to a constant.\n- **GPU particles allocate but never draw.** No render program is loaded and the indirect draw count\n  is never written.\n- **Several subsystems are unreachable from `main()`** — the action-mapping `InputSystem`, the\n  `EventBus`, `SystemScheduler`, the audio stack, and the `.import` asset pipeline. They compile and\n  are unit-tested; they are not connected.\n- **Keyboard shortcuts are display-only** apart from undo/redo and the gizmo keys. Menu chords render\n  from `ShortcutRegistry` but nothing dispatches them.\n- **Play / Pause / Stop change editor state only.** No scene snapshot or restore.\n- **The backend abstraction is cosmetic.** `RenderingDevice` exists, but consumers cast to\n  `GLRenderingDevice` to reach the raw handle, so it is not yet a seam a second backend could use.\n- **`GameExporter` is vestigial**, still shaped around the FPS demo removed in 0.5.0.\n\n---\n\n## Project layout\n\n```\nMistEngine/\n├── include/            Public headers (ECS, Renderer, Editor, Core, Script, …)\n├── src/                Implementation\n├── shaders/            51 GLSL shaders (#version 460 core)\n├── scripts/            Lua — bootstrap.lua is the opening scene\n├── tests/              Catch2 suite, headless\n├── modules/            Example hot-loadable plugin\n├── docs/               Architecture and user guides\n└── CMakeLists.txt\n```\n\nThe editor's opening scene is authored in `scripts/showcase.lua` — edit that, not C++, to change\nwhat you see on launch.\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Enable the pre-commit hook once per clone:\n\n```bash\ngit config core.hooksPath .githooks\n```\n\nIt runs `clang-format` over staged sources and rejects trailing whitespace.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Acknowledgments\n\nBullet Physics · GLFW · GLM · Dear ImGui · ImGuizmo · Assimp · Lua & sol2 · nlohmann/json · Catch2 ·\nstb_image · glad\n",
  "bytes": 7816,
  "sha": "694f589e589975aacc9c4ab92ec5aa0393292345946305f6adcf950a2881862c",
  "repo_slug": "aayushmishraaa/mistengine",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_aayushmishraaa_mistengine_docs_okf_index_5d17b228/readme"
}