VoxelCore: Building a C++ Voxel Engine with CMake

What VoxelCore Is Built to Support

VoxelCore is positioned as a voxel game engine written in C++. It is aimed at developers who need source code and graphics dependencies for an OpenGL-oriented voxel application, rather than users looking for a packaged game runtime. The repository includes `src/`, `res/`, `dev/`, `test/`, `vctest/`, documentation, a `CHANGELOG.md`, and CMake configuration files. Based on that layout, engine code, resources, tests, developer assets, and build configuration are separated at the top level.

The documented dependency set gives a more concrete indication of its scope. OpenGL-related libraries include GLFW, GLEW, and GLM. Audio and asset support include OpenAL, Ogg Vorbis, PNG, and FreeType. LuaJIT, curl, OpenSSL, and EnTT add scripting, networking or transfer capabilities, cryptography support, and an entity-component framework dependency. Those names do not prove how extensively each subsystem is used, but they do show that compiling the engine requires more than a C++ compiler alone.

VoxelCore also includes an application target named `VoxelCore`, as shown by the Docker run command. That makes it relevant to developers who want to inspect and modify a complete engine repository. The README does not describe it as a general-purpose rendering library with a stable public API, nor does it document a plugin SDK, supported engine versions, or compatibility guarantees for downstream games. It is better evaluated as a C++ game-engine codebase than as a drop-in library.

VoxelCore's Native Rendering and Runtime Dependencies

The build documentation centers on native libraries. Linux instructions provide package sets for ALT, Debian, RHEL, and Arch families. macOS uses Homebrew, while Windows uses vcpkg. This variation matters because VoxelCore is not presented as a self-contained source tree that only needs CMake. A developer must ensure that the development packages, headers, link libraries, and toolchain agree on each operating system.

EnTT receives special treatment because the README pins `v3.16.0` as the last version that supports C++17. The Linux instructions install that release before configuring VoxelCore. macOS requests `skypjack/entt/entt` through Homebrew, and Windows leaves dependency acquisition to vcpkg. The Dockerfile independently clones the same EnTT version, which gives a useful reference for a repeatable Linux container setup.

The native dependency surface creates a real maintenance consideration. Package availability can differ across Linux distributions, Homebrew can fail for Lua, LuaJIT, or OpenAL Soft, and the README says those packages may need manual compilation. VoxelCore also documents a LuaJIT discovery workaround on some CMake setups. That workaround creates filesystem symlinks under system paths, so it is a targeted fix rather than evidence that every Debian installation needs modification. The project docs do not explain the underlying CMake lookup failure in detail.

Building VoxelCore on Linux with CMake

The simplest documented Linux path starts with the appropriate native packages. After installing them, clone the repository recursively and use its CMake configuration. The recursive clone matters because the documented command includes submodules even though the README excerpt does not enumerate them.

For a Debian-based system, install the documented development packages before cloning:

sudo apt install libglfw3 libglfw3-dev libglew-dev libglm-dev libpng-dev libopenal-dev libluajit-5.1-dev libvorbis-dev libcurl4-openssl-dev libssl-dev libfreetype6-dev

If EnTT is not already available through the selected package source, the README gives this separate source build. Run it before configuring VoxelCore:

git clone --branch v3.16.0 https://github.com/skypjack/entt.git
cd entt
mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DENTT_INSTALL=ON ..
sudo make install

The README warns not to use this EnTT installation method on ALT Linux. For that distribution, its package-based instructions include `entt-devel` and other development libraries instead.

Clone, configure, and compile the engine with the commands published in the README:

git clone --recursive https://github.com/MihailRis/VoxelCore.git
cd VoxelCore
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel

The result should be a build tree containing the `VoxelCore` executable, although the README does not print the final compiler or linker output. It also does not describe an installation step after compilation.

Windows and macOS Build Routes in VoxelCore

On Windows, the documented prerequisites are vcpkg, CMake, Git, and Visual Studio with C++ tools. The README notes that `VCPKG_ROOT` is often already set in the Developer Command Prompt for Visual Studio. Otherwise, it shows how to clone vcpkg and run its bootstrap script.

A current PowerShell session can receive the vcpkg location shown in the project instructions:

$env:VCPKG_ROOT = "C:\vcpkg"
$env:PATH = "$env:VCPKG_ROOT;$env:PATH"

VoxelCore then uses a named CMake preset rather than the Linux `mkdir build` sequence:

git clone --recursive https://github.com/MihailRis/VoxelCore.git
cd VoxelCore
cmake --preset default-vs-msvc-windows
cmake --build --preset default-vs-msvc-windows

The preset is defined in the repository's `CMakePresets.json`. The README warns that `CMakeUserPresets.json`, if present, must contain the correct `VCPKG_ROOT` path. It also provides a separate CLion route using vcpkg, CMake, Ninja, and MinGW. Paths containing spaces are specifically discouraged for that toolchain because they may break `windres`.

macOS follows a shorter documented setup. Install the listed Homebrew packages, then use the same recursive clone and CMake sequence as Linux:

brew install glfw3 glew glm libpng libvorbis lua luajit libcurl openal-soft skypjack/entt/entt freetype

Homebrew failure for `lua`, `luajit`, or `openal-soft` is an acknowledged case. The README says to download, compile, and install those packages manually, but it does not prescribe one universal installation method.

Docker Builds and the X11 Display Boundary

VoxelCore includes a `Dockerfile` based on `debian:bookworm-slim`. The file installs the compiler, CMake, graphics, audio, LuaJIT, curl, FreeType, OpenSSL, and related packages. It then installs CMake `3.27.9` manually and builds EnTT `v3.16.0`. This makes the container more reproducible for the documented Linux build, but it does not turn VoxelCore into a portable binary for systems without a compatible display path.

From the repository root, build the image with the README command:

docker build -t voxel-engine .

Compile inside the mounted source tree as follows:

docker run --rm -it -v "$(pwd):/project" voxel-engine bash -c "cmake -DCMAKE_BUILD_TYPE=Release -Bbuild && cmake --build build --parallel"

Running the engine still requires X11 forwarding on Linux:

docker run --rm -it \
  -v "$(pwd):/project" \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v "$XAUTHORITY:/home/user/.Xauthority:ro" \
  -e DISPLAY="$DISPLAY" \
  --network=host \
  voxel-engine ./build/VoxelCore

This exposes a concrete boundary in the Docker path. The container is documented as a build and GUI execution environment, not as a headless service. On Windows, the README says that an X server such as VcXsrv is required. It also sets `--network=host`, so adopting this exact command means accepting that network configuration rather than treating it as an isolated default.

VoxelCore's Limits as a Production Engine

The first limitation is setup cost. VoxelCore requires a native C++ toolchain and several system libraries across Linux, macOS, and Windows. The separate operating-system instructions, vcpkg configuration, Homebrew exceptions, EnTT pin, and LuaJIT workaround all add places where a build can diverge. A repository that is easy to clone is not the same as an engine that is easy to package.

The second limitation is the lack of a documented engine integration contract in the README. It explains how to clone and compile the project, and the Docker example runs `./build/VoxelCore`, but it does not document a stable embedding API, supported game formats, save-file compatibility, renderer backend guarantees, input requirements, or migration procedures. It also does not describe rollback or a version support policy. The presence of `CHANGELOG.md` and recent tagged releases provides records to inspect, but the README excerpt does not explain their compatibility guarantees.

A third constraint is the LuaJIT and CMake combination. Some Debian configurations require extra symlinks before CMake can locate Lua. Those changes use root privileges and assume particular library and include paths. A different distribution, library layout, or architecture may require a different correction, but the README does not provide those alternatives.

Docker does not remove the display requirement. Linux needs mounted X11 sockets, authorization, `DISPLAY`, and host networking. Windows needs an external X server. VoxelCore is therefore the wrong choice when the target environment is headless and the application must run without an OpenGL display path, unless the team already has that separate infrastructure.

VoxelCore Compared with Engine SDK and Asset Tooling

A real alternative is a managed engine SDK that supplies its own editor, build pipeline, packaged runtime, and platform templates. Its approach differs from VoxelCore's documented workflow. Instead of installing GLFW, GLEW, GLM, LuaJIT, OpenAL, and related packages and invoking CMake directly, a managed SDK generally asks the developer to create and export a project through the vendor's tooling. That may reduce manual dependency setup, but it also introduces vendor-specific project formats, licensing, and platform requirements.

Another alternative is to use VoxelCore as a source reference while building production rendering, asset, audio, and scripting infrastructure separately. This approach treats the repository as a C++ codebase to inspect rather than a complete delivery platform. It avoids assuming that the checked-in application target satisfies a game's packaging requirements, but the project would then need its own subsystem ownership and engineering work.

For an engineer deciding between these paths, the relevant distinction is operational. VoxelCore exposes native build control and direct access to its C++ implementation. A managed SDK offers a defined editor and export workflow. A separate codebase offers control over architecture but requires implementation of missing project infrastructure. The README does not provide quality scores or adoption evidence, so this comparison should stay grounded in those documented workflow differences.

VoxelCore Maintenance, Releases, and MPL-2.0

VoxelCore is not archived, and its last push was on 2026-10-16. Releases `v0.32.5`, `v0.32.4`, and `v0.32.3` were published on 2026-10-13, 2026-10-11, and 2026-10-11 respectively. These facts indicate recent project activity at that point, but they do not establish a long-term support period or compatibility promise for each minor version.

The repository contains `CHANGELOG.md`, so version-level changes can be investigated there before upgrading. However, the README excerpt does not describe semantic versioning, an upgrade guide, migration scripts, or a supported release channel. It also does not say whether saves, resources, or generated projects can move directly between releases. An upgrade therefore needs review of the changelog and build changes for the selected version.

The repository is licensed under MPL-2.0. Under that license, covered files generally carry file-level obligations, including making source code for modifications available under the same license when distributing them. The exact treatment of a particular modification or distribution depends on the files involved. This is not legal advice. Teams modifying and redistributing VoxelCore should review the actual `LICENSE` and understand which files are covered before choosing an integration model.

Editorial conclusion

Adopt VoxelCore when you want a C++ and OpenGL-oriented codebase for a voxel game and can own its native build dependencies. Do not choose it if you need a turnkey editor, a documented cross-platform SDK, or a managed runtime with minimal setup. Verify first that the required graphics, audio, LuaJIT, and packaging dependencies resolve cleanly in the target toolchain, since the README provides builds rather than a reusable library installation procedure.

Frequently asked questions

Official sources

1. Issues
2. License: MPL-2.0
3. MihailRis/voxelcore on GitHub
4. README
5. Releases