voxelcore/README.md
alexei-zebra b5416d1219
Fix the issues found while reviewing the Wayland frame work
A review of the branch turned up a number of defects, gaps and leftovers;
this commit addresses all of them.

Defects:
- the shadow uniform array held seven entries while eight locations were
  written, so the last one landed outside the object;
- CursorShape::LAST stayed in the middle of the enum after the new corner
  shapes were appended, which made the GLFW cursor table read out of
  bounds; the extra shapes are now mapped onto the ones GLFW knows, and
  the table is only filled for those;
- GlStateGuard asked glIsEnabled for an attribute pname, so it always got
  GL_INVALID_ENUM and never restored the vertex attribute arrays;
- the early returns in wayland_window_initialize left the global window
  and input pointers dangling when falling back to GLFW;
- the icon textures were listed nowhere, so none of them ever loaded;
- a shader failure disabled the shadow after the surface had already been
  sized for it, and VOXEL_DECORATIONS outlived the switch cleanup.

Behavior:
- the keyboard now releases every pressed key when it loses focus, and a
  repeat rate of zero means no repeat;
- the fourth UTF-8 lead byte is decoded with the right mask, control
  characters no longer reach text fields, and a vanished clipboard offer
  clears the cached text;
- compositor side decorations disable ours again instead of leaving two
  titles, the window destructor releases the rest of the state, and the
  content inset is computed before the GUI acts so the HUD and the
  container never disagree for a frame; the HUD clamps it;
- the window controls fall back to minimize, maximize and close, and the
  icons are drawn from textures only.

Cleanups: one monotonic timer instead of three, one vertex shader shared
by both renderers with a link check, one button layout parser, the inset
rule moved into Screen, the scissor stack moved into the base Window
(about 110 duplicated lines), named shadow and evdev constants, trimmed
includes, a README note about the Wayland dependencies, and the long
lines introduced by this branch wrapped.
2026-10-10 12:23:42 +03:00

5.8 KiB

voxel-core VoxelCore

Latest release


Build project in Linux

Install libraries

Install EnTT

Installing last version that supports C++17.

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

Warning

If you are using ALT Linux, do not use this EnTT installation method.

ALT Linux based distros

su -
apt-get install entt-devel libglfw3-devel libGLEW-devel libglm-devel libpng-devel libvorbis-devel libopenal-devel libluajit-devel libstdc++13-devel-static libcurl-devel libfreetype-devel libssl-devel

Debian based distros

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

#### Wayland (optional, enabled by default on Linux)

The native Wayland backend needs `wayland-client`, `wayland-egl`,
`wayland-scanner`, `wayland-protocols`, `libxkbcommon` and EGL. Build with
`-DVOXELENGINE_WAYLAND=OFF` to fall back to GLFW; `libsystemd` (sd-bus) is
picked up automatically for the desktop button layout.

Tip

CMake missing LUA_INCLUDE_DIR and LUA_LIBRARIES fix:

sudo ln -s /usr/lib/x86_64-linux-gnu/libluajit-5.1.a /usr/lib/x86_64-linux-gnu/liblua5.1.a
sudo ln -s /usr/include/luajit-2.1 /usr/include/lua

RHEL based distros

sudo dnf install glfw-devel glew-devel glm-devel libpng-devel libvorbis-devel openal-soft-devel luajit-devel libcurl-devel libfreetype-devel openssl-devel

Arch based distros

sudo pacman -S glfw glew glm libpng libvorbis openal luajit curl freetype2 openssl

Building engine with CMake

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

Tip

Use --parallel to utilize all CPU cores during build.


Building project in macOS

Install libraries

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

Tip

If Homebrew fails to install lua, luajit, or openal-soft, download, compile, and install them manually.

Building engine with CMake

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

Building in Windows

Note

Requirements: vcpkg, CMake, Git, and Visual Studio (with C++ tools).

There are two options to use vcpkg:

  1. If you have Visual Studio installed, the VCPKG_ROOT environment variable is often already set in the Developer Command Prompt for VS.
  2. Otherwise, install vcpkg manually:
cd C:\
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

Then set the VCPKG_ROOT environment variable and add it to PATH:

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

Tip

For troubleshooting, refer to the official vcpkg documentation.

After installing vcpkg, build the project:

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

Note

Make sure your CMakeUserPresets.json (if used) contains the correct VCPKG_ROOT path.


Building with CLion (MinGW / Ninja)

Note

Requirements: vcpkg, Git, and CLion (bundled with CMake, Ninja and MinGW toolchain).

Warning

Avoid installing tools in paths with spaces (e.g. Program Files). This may break MinGW builds (especially windres).

Install vcpkg manually as described in the Visual Studio section.

Configure CLion

Open the project in CLion and configure CMake profile:

Settings → Build, Execution, Deployment → CMake

Reload CMake project and build the engine.


Build using Docker

Note

First, install Docker Engine: https://docs.docker.com/engine/install

On Linux

Step 1. Build Docker image

docker build -t voxel-engine .

Step 2. Build project inside container

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

Step 3. Run the application (requires X11 forwarding)

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

On Windows

Note

You need an X server like VcXsrv to display the GUI.

Step 1. Install and run VcXsrv

Launch with:

.\vcxsrv.exe :0 -multiwindow -ac

Step 2. Build Docker image

docker build -t voxel-engine .

Step 3. Build project

docker run --rm -it -v "${PWD}:/project" voxel-engine bash -c "cmake -DCMAKE_BUILD_TYPE=Release -Bbuild && cmake --build build --parallel"

Step 4. Run the application

docker run --rm -it -v "${PWD}:/project" -e DISPLAY=host.docker.internal:0.0 --network=host voxel-engine ./build/VoxelCore