ylikuutio icon indicating copy to clipboard operation
ylikuutio copied to clipboard

verified publisher icon nrz
→

Metadata

Ylikuutio 3D engine

Ylikuutio. A 3D game and simulation engine.

A hobby project of mine. Work in progress.

License: AGPL v3 GitHub Actions CodeQL Codacy Badge Quality Gate Status

License

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.

Overview

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.

Ylikuutio 0.0.8 screenshots

View of Helsinki with cats and Ylikuutio console Turbo polizei and cats Cats and debug console commands Turbo polizei and debug console commands

Articles

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.

Compiling

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.

Native compiling

Debian or Ubuntu

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

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.

Windows

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.

Cross compiling

Cross compiling from Debian to Windows

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

Compiling in a Podman container

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.

Software shipped with Ylikuutio

Ylikuutio repository contains the following games/demos:

Hirvi

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

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

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

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

YliEdit is a universe editor for Ylikuutio. Work in progress.

Running software

GNU/Linux

$ ./hirvi
$ ./tulevaisuus
$ ./ajokki
$ ./gpgpu_test
$ ./yli_edit

hirvi.exe, tulevaisuus.exe, ajokki.exe, gpgpu_test.exe, and yli_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

Windows

> hirvi.exe
> tulevaisuus.exe
> ajokki.exe
> gpgpu_test.exe
> yli_edit.exe

Ylikuutio usage

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 see code/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_scene
  • activate helsinki_east_downtown_scene
  • set red 1.0
  • set green 0.15
  • set blue 0.77
  • print red
  • print green
  • print blue
  • set x 123
  • set y 456
  • set z 789
  • print x
  • print y
  • print z
  • info
  • info cat_species
  • info cat2
  • set wireframe true
  • set wireframe false
  • activate turbo_polizei_camera
  • print turbo_polizei_png2.cartesian_coordinates
  • print turbo_polizei_png2.x
  • print turbo_polizei_png2.y
  • print turbo_polizei_png2.z
  • set turbo_polizei_png2.y 50
  • set turbo_polizei_png2.x 100
  • set turbo_polizei_png2.z 200
  • activate cat_camera
  • print cat1.cartesian_coordinates
  • print cat1 x
  • print cat1.y
  • print cat1.z
  • set cat1.x 123.45
  • set cat1.z 210
  • bind helsinki_east_downtown_orange_fur_material helsinki_east_downtown_grayscale_shader
  • bind helsinki_east_downtown_orange_fur_material helsinki_east_downtown_shader
  • print cat1.speed
  • bind cat1 orient_to_south_brain
  • bind cat1 orient_and_go_east_brain
  • set cat1.speed 1
  • bind cat1 orient_and_go_west_brain
  • bind cat1 rest_brain
  • print framebuffer_width
  • print framebuffer_height
  • screenshot screenshot1.data
  • set framebuffer_width 2000
  • set framebuffer_height 1000
  • screenshot screenshot2.data
  • print window_width
  • print window_height
  • set window_width 1000
  • set window_height 500
  • create-object cat_species cat3 500 100 600 3.14 0
  • create-object cat_species cat4 500 100 650
  • create-holobiont turbo_polizei_png_symbiosis polizei3 500 100 700 3.14 0
  • create-holobiont turbo_polizei_png_symbiosis polizei4 480 100 700

FAQ

Q: 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.

Implemented functionality

  • 3D rendering
  • 2D text
  • support for different height map formats (SRTM, PNG)
  • instant rebinding of instances of classes belonging to ontological hierarchy
  • callbacks
  • fully functioning in-game console
  • multiple scenes in the same Universe (activate console command)
  • audio with SoLoud.
  • option for wireframe models (set wireframe true, set wireframe false)
  • GPGPU using yli::ontology::ComputeTask class (see also Skrolli 2019.2 for an article in Finnish).

Future developments underway

  • full support for different keyboard layouts in console
  • custom keyboard mappings
  • command to read console command input from file
  • command to record gameplay
  • command to play recorded gameplay
  • copy-paste in console (Shift-Ins for paste)
  • console reference manual (man command)
  • rendering to texture (for mirrors and displays)
  • partially transparent 2D text
  • 3D text
  • partially transparent 3D text
  • coordinates relative to other objects, not only to Universe object
  • practically infinite voxel worlds (limited by float precision)
  • collision detection between objects
  • octree space partitioning
  • possibility to create scenes with different spatial scales
  • background loading of Scenes
  • objects (Species in Ylikuutio terminology) with modifiable vertices
  • making holes in objects
  • splitting of objects into 2 or more pieces
  • cementing of 2 or more objects into one
  • morphing between objects (Species in Ylikuutio terminology)
  • morphing between objects (Species) and 3D text (Glyphs)
  • ray casting for vertex selection and vertex modifications
  • vegetation created with L-system fractals
  • objects with 4 or more spatial dimensions, projected to 3D space before rendering to screen
  • more shaders
  • sky dome
  • railways
  • roads
  • trains, trams, and road vehicles
  • more realistic static water
  • flowing water
  • snow and ice
  • more physics
  • artificial intelligence (AI) creatures
  • A* and Theta* pathfinding
  • visual pattern recognition for AI: V1 (primary visual cortex) and V2 simulation
  • GUI for scripting, asset creation etc.
  • Network gaming

Libraries currently in use

Libraries not yet in use

3D models

Textures

Fonts

  • kongtext font is made by codeman38, see res/fonts/kongtext/license.txt for the license.

Map data

Audio

Trademarks

Contributions and bugfixes

  • Antti Nuortimo (most of Ylikuutio code)
  • Mikko Rasa (programming advice and bugfixes)
  • Ronja Koistinen (support for building in a Podman container)

Contact info

(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
email antti dot nuortimo at gmail dot com
(please write 'ylikuutio' to email title to escape /dev/null)

Work offers are also very welcome!

← Metadata

21
Stars
3
Forks
Watchers

Owner

verified publisher icon nrz

Metadata

Ylikuutio 3D engine

Back