Ylikuutio 3D engine
A hobby project of mine. Work in progress.
Ylikuutio is under The GNU Affero General Public License 3,
or (at your option) any later version. See COPYING file.
All my code copyright (C) 2015-2025 Antti Nuortimo.
An exception in licensing of Ylikuutio code are
Asio example source code files modified by me, which have
their original Boost Software License - Version 1.0.
Data preprocessing scripts that use Blender Python API
are not a part of Ylikuutio itself and they are under
The GNU General Public License 2 or later (at your option),
following Blender’s licensing.
Ylikuutio is a 3D game engine designed for 3D games and simulations.
Ylikuutio aims to run fast and support also older hardware.
Currently Ylikuutio works on 64-bit GNU/Linux, MacOS, and Windows systems.
OpenGL 3.3 is required. Vulkan is required.
In Skrolli 2018.4 there is an article
“Pelimoottori harrastusprojektina” (in Finnish, translation: “Game engine
as a hobby project”). Skrolli 2018.4 can be freely downloaded as PDF.
In Skrolli 2019.2 there is an article
“GPGPU-laskenta” (in Finnish, translation: “GPGPU computation”).
Skrolli 2019.2 can be freely downloaded as PDF.
Ylikuutio can be compiled with GCC, Clang or Visual Studio.
In Visual Studio compiling may break due to compiler-specific bugs.
Cross compiling from Linux® to Windows using MinGW-w64 works fine.
C++20 support is required.
CMake 3.14 or newer is needed for the compiling process.
Ylikuutio repository in GitHub has 2 branches: master & coverity_scan.master is the branch that should be up to date and it’s the one to build.
In Debian or Ubuntu it’s simple.
First, install all the necessary compilers, tools and libs. You may use
your favorite package manager such as apt, aptitude, apt-get, yum etc.
You all need these packages:
cmake make g++ gcc libx11-dev libgl1-mesa-dev libglu1-mesa-dev libpng-dev libsdl2-dev libvulkan-dev libxcursor-dev libxrandr-dev libxext-dev libxi-dev libxinerama-dev vulkan-validationlayers-dev zlib1g-dev
Eg. with apt:
$ sudo apt install cmake build-essential libx11-dev libgl1-mesa-dev libglu1-mesa-dev libpng-dev libsdl2-dev libvulkan-dev libxcursor-dev libxrandr-dev libxext-dev libxi-dev libxinerama-dev vulkan-validationlayers-dev zlib1g-dev
If you are doing a cross compile from Linux to Windows, you need also:
$ sudo apt install g++-mingw-w64 gcc-mingw-w64 gfortran-mingw-w64 binutils-mingw-w64 libz-mingw-w64-dev
Ylikuutio uses Git submodules, so you need to update them:
$ git submodule update --init --recursive
Then, to compile with GCC, in Ylikuutio install directory:
$ mkdir build$ cd build$ cmake ..$ make
To make compiling faster you probably want to use several threads:
$ make -j $(($(nproc) - 1))
Or, to compile with Clang, again in Ylikuutio install directory:
$ mkdir build$ cd build$ export CC="$(which clang)"$ export CXX="(which clang++)"$ cmake ..$ make
If you have problems compiling tests or for some other reason don’t want
to compile tests, in CMakeLists.txt comment out the line that says:set(DO_UNIT_TESTS_WITH_GOOGLE_TEST true)
MacOS 10.14 or newer is needed for compiling in MacOS.
Ylikuutio uses Git submodules, so you need to update them:
$ git submodule update --init --recursive
Install command line building tools:
$ gcc
Proceed with the opening pop-up install menu.
You should now be able to run gcc, clang, g++, clang++, and make.
Download CMake binary from https://cmake.org/download/ .
Install CMake:
$ sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install
You should now be able to run cmake in terminal.
You can build like on Debian or Ubuntu:
$ mkdir build$ cd build$ cmake ..$ make
Building unit tests does not currently work on MacOS,
so by default they are not built MacOS.
Compiling in Visual Studio is more difficult. The recommended way to
get a binary for Windows is to cross compile from Linux to Windows. See below.
To cross compile from GNU/Linux to Windows:
$ mkdir build_windows$ cd build_windows$ cmake -DDIRECTX=FALSE -DCMAKE_TOOLCHAIN_FILE=../w64.cmake ..$ make
Crosscompiling from GNU/Linux to Windows fails to compile tests.
This is a known bug in Google Test. Just run make again if
compiling ends before you get hirvi.exe, tulevaisuus.exe,ajokki.exe, gpgpu_test.exe, and yli_edit.exe.
By default compiling tests is disabled when crosscompiling from Linux
to Windows, due to this issue:
https://github.com/google/googletest/issues/606
You may build Ylikuutio also in a Podman container. See instructions. Building tested in CentOS 8.
The built executable is not self-contained so you still need the dependencies.
Support for self-contained executables may be added in the future.
Ylikuutio repository contains the following games/demos:
Hirvi is a first person action-adventure of the adventures of
a moose/elk called Hirvi. Cities are dangerous places for moose, and
in particular an encounter with the police may prove deadly for Hirvi,
even through moose are well-known pasifists.
“hirvi” means a moose/elk in Finnish.
Hirvi is a work in progress.
Tulevaisuus (“the future” in Finnish) is
a turn-based 3D tactical combat game with programmable robots.
The robots controlled by an evil AI have taken over the world. Almost.
The last hope of the human species is the Lisp Resistance Force.
You, as the lead Lisp hacker of the Lisp Resistance Force,
are responsible for the programming of the robots of
the Lisp Resistance Force. Your task is write Lisp
to control the robots reowned by humans.
And save the human species, too.
Tulevaisuus is a work in progress.
Ajokki is sandbox demo program to check out some properties of
Ylikuutio 3D engine. “Ajokki” is a working title named after
a Finnish bus body manufacturer.
GPGPU test is a simple GPGPU example. It computes e.g. the distances
between some railway stations on the current passenger railway network
of Finland using both floating point and unsigned short values, using
Floyd-Warshall algorithm. GPGPU test includes also some simpler examples
on how to copy data and how to shift textures. After computing,
e.g. Bash scripts code/bash/print_float_results_of_width_32 &code/bash/print_integer_results_of_width_32 can be used to display
the Floyd-Warshall results in Bash.
YliEdit is a universe editor for Ylikuutio. Work in progress.
$ ./hirvi$ ./tulevaisuus$ ./ajokki$ ./gpgpu_test$ ./yli_edit
hirvi.exe, tulevaisuus.exe, ajokki.exe, gpgpu_test.exe, andyli_edit.exe can also be executed in Linux, using Wine:
$ wine ./hirvi.exe$ wine ./tulevaisuus.exe$ wine ./ajokki.exe$ wine ./gpgpu_test.exe$ wine ./yli_edit.exe
> hirvi.exe> tulevaisuus.exe> ajokki.exe> gpgpu_test.exe> yli_edit.exe
Press `` to get console. Press F to toggle flying on off.
Arrow keys work too. Ctrl is turbo. F1 toggles help display
and there you’ll see some more options to try.
To run tests (coverage is still quite limited but underway):
$ ./unit_tests_with_googletest
This part reflects the current usage of Ylikuutio and will change as new
functionality is implemented.
At the moment, you need a main function (for an example, please seecode/hirvi/hirvi.cpp and code/ajokki/ajokki.cpp) which starts your
game/simulation (initialization), runs the game/simulation (the main loop)
and ends the program (cleaning-up). In all these phases mentioned above
Ylikuutio library functions may be used. Ylikuutio library code is located
in code/ylikuutio/ tree. Ylikuutio code may change a lot and so far no
stable API has been defined. There are also some application code snippets
in code/ylikuutio/snippets/ directory. Hirvi, Ajokki and Ylikuutio code
itself are the best references on how to use Ylikuutio in practice.
Some available console commands to try in Ajokki:
activate joensuu_center_and_west_sceneactivate helsinki_east_downtown_sceneset red 1.0set green 0.15set blue 0.77print redprint greenprint blueset x 123set y 456set z 789print xprint yprint zinfoinfo cat_speciesinfo cat2set wireframe trueset wireframe falseactivate turbo_polizei_cameraprint turbo_polizei_png2.cartesian_coordinatesprint turbo_polizei_png2.xprint turbo_polizei_png2.yprint turbo_polizei_png2.zset turbo_polizei_png2.y 50set turbo_polizei_png2.x 100set turbo_polizei_png2.z 200activate cat_cameraprint cat1.cartesian_coordinatesprint cat1 xprint cat1.yprint cat1.zset cat1.x 123.45set cat1.z 210bind helsinki_east_downtown_orange_fur_material helsinki_east_downtown_grayscale_shaderbind helsinki_east_downtown_orange_fur_material helsinki_east_downtown_shaderprint cat1.speedbind cat1 orient_to_south_brainbind cat1 orient_and_go_east_brainset cat1.speed 1bind cat1 orient_and_go_west_brainbind cat1 rest_brainprint framebuffer_widthprint framebuffer_heightscreenshot screenshot1.dataset framebuffer_width 2000set framebuffer_height 1000screenshot screenshot2.dataprint window_widthprint window_heightset window_width 1000set window_height 500create-object cat_species cat3 500 100 600 3.14 0create-object cat_species cat4 500 100 650create-holobiont turbo_polizei_png_symbiosis polizei3 500 100 700 3.14 0create-holobiont turbo_polizei_png_symbiosis polizei4 480 100 700Q: What is “Ylikuutio”?
A: In Finnish, “yli” means “over”,
and “kuutio” means “cube”.
So, “Ylikuutio” is a reference to a hypercube.
Q: How is Ylikuutio software developed?
A: In Debian GNU/Linux
(Debian Bookworm at the moment),
using Vim. Other tools in use include
Valgrind, KCachegrind,
GDB, GitHub Actions,
Codacy, CodeQL,
SonarCloud, and Coverity Scan.
Q: For what kinds of software Ylikuutio can be used?
A: Ylikuutio can be used for all kinds of 3D games and simulations.
At the moment no specific support for 2D is available, but naturally
3D graphics can also be used to present a 2D world.
Q: What are the design goals for Ylikuutio?
A: Ylikuutio aims to be a fast and flexible 3D game/simulation engine
and fulfil my own requirements for my own indie game projects.
Ylikuutio aims to run fast also on low-end video cards.
Higher detail level may be offered for high-end video cards.
Q: What are the target platforms of Ylikuutio?
A: Currently supported target platforms are Linux, MacOS, and Windows.
Cross-compiling from Linux to Windows works!
Currently only 64-bit environments are supported.
Q: What graphics APIs Ylikuutio uses?
A: Ylikuutio targets OpenGL version 3.3. Vulkan support is a work in progress.
Q: Does Ylikuutio use modern OpenGL (VAOs and VBOs etc.)?
A: Yes, Ylikuutio uses VAOs (vertex array objects), VBOs (vertex buffer
objects), index buffers, and UBOs (uniform buffer objects).
Q: Is Ylikuutio based on some other 3D engine?
A: Some parts of Ylikuutio (some shaders, some file loaders, etc.) are
based on https://www.opengl-tutorial.org/,
which I really recommend for anyone interested in learning
OpenGL programming. Ylikuutio also uses external libraries such as
(in alphabetical order) Asio, GLEW, GLM, libpng, OpenFBX, pugixml,
SDL, SoLoud, and zlib.
The rest is written from scratch.
Q: Does Ylikuutio use right-handed or left-handed world coordinates?
A: Ylikuutio uses right-handed world coordinates,
so X grows eastward, Z grows southward, and Y grows upwards.
Q: Is there a scripting language in Ylikuutio?
A: YliLisp scripting language is a work in progress. See YliLisp design notes.
Universe (activate console command)set wireframe true, set wireframe false)yli:
:ComputeTask class (see also Skrolli 2019.2 for an article in Finnish).man command)Universe objectfloat precision)ScenesSpecies in Ylikuutio terminology) with modifiable verticesSpecies in Ylikuutio terminology)Species) and 3D text (Glyphs)horse.fbx file shipped with Ylikuutio is made from the original horse.blend by exporting the object in FBX file format, using Blender.turbo_polizei.fbx file shipped with Ylikuutio is made from the original porche_997_turbo_polizei_blendswap.blend (sic) by exporting the object in FBX file format, using Blender.freight_train.fbx file shipped with Ylikuutio is made from the original freight.blend by exporting the object in FBX file format, using Blender.cat.fbx file shipped with Ylikuutio is made from the original cat.blend by exporting the object in FBX file format, using Blender.orange_fur_texture.png is scaled down and converted into PNG from the original ornage-fur-texture.jpg (sic). License conditions are available on My Free Textures License/TOU page.pavers1b2.png is scaled down and converted into PNG from the original pavers1b2.jpg. License conditions are available on My Free Textures License/TOU page.416882__greek555__blue-play.mp3.419588__greek555__dreaming-of-me.mp3.395487__frankum__tecno-pop-base-and-guitar-2.mp3.(found bugs are very welcome!)
(at them moment I do not take code contributions)
| variable | value |
|---|---|
| name | Antti Nuortimo |
| GitHub | https://github.com/nrz |
| Stack Overflow | https://stackoverflow.com/users/1310991/nrz |
| antti dot nuortimo at gmail dot com | |
| (please write ‘ylikuutio’ to email title to escape /dev/null) |
Work offers are also very welcome!