Ylikuutio. A 3D game and simulation engine.

A hobby project of mine. Work in progress.

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-2024 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

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: google/googletest#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

• The source code from https://www.opengl-tutorial.org/ is licensed under WTFPL Public Licence version 2.
• Asio is licensed under Boost software license.
• libpng is licensed under PNG Reference Library License version 2.
• OpenGL Mathematics (GLM) is licensed under The Happy Bunny License (Modified MIT License) and MIT License.
• The OpenGL Extension Wrangler Library (GLEW) is licensed under the Modified BSD License, the Mesa 3-D License (MIT) and the Khronos License (MIT).
• OpenFBX is licensed under the MIT license.
• SDL2 is licensed under the zlib license.
• SoLoud is licensed under the zlib license.
• pugixml is licensed under the MIT license.
• zlib is licensed under the zlib license.

Libraries not yet in use

• Google logging module (glog) is licensed under the conditions available in https://github.com/google/glog/blob/master/COPYING.
• FastNoiseSIMD is licensed under the MIT license.
• TinySpline is licensed under the MIT license.
• fastgltf is licensed under the MIT license.

3D models

• 3D model of Helsinki. The administrator of 3D model of Helsinki is Helsingin kaupunginkanslia and the original creator is Helsingin kaupungin kaupunginkanslia, tietotekniikka- ja viestintäosasto. The data has been downloaded from the Helsinki Region Infoshare service 19.11.2017 using the license Creative Commons Nimeä 4.0 Kansainvälinen (CC BY 4.0).
• Horse is made by b2przemo and it is licensed under Creative Commons Attribution 3.0 Unported (CC BY 3.0) license. The 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 is made by corvusd and it is licensed under Creative Commons Attribution 3.0 Unported (CC BY 3.0) license. The 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 is made by SONGKRO and it is licensed under CC0 1.0 Universal (CC0 1.0) Public Domain Dedication . The freight_train.fbx file shipped with Ylikuutio is made from the original freight.blend by exporting the object in FBX file format, using Blender.
• Rigged and animated cat is made by JonasDichelle and it is licensed under Creative Commons Attribution 3.0 Unported (CC BY 3.0) license. The cat.fbx file shipped with Ylikuutio is made from the original cat.blend by exporting the object in FBX file format, using Blender.
• Suzanne the monkey is a standard Blender object. According to Blender license information: "All your artwork – images or movie files – including the .blend files and other data files Blender can write, is free for you to use as you like." Ylikuutio does not contain any code from Blender, however. Blender itself is released under the GNU General Public License (GPL) 2 or later.

Textures

• Grass texture is from Free Seamless Green Grass Textures, licensed under Creative Commons Attribution (BY) License.
• A Cool Seamless Orange Fur Texture is from My Free Textures. 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.
• Pink Marble Pavers Or Tiles Background Texture is from My Free Textures. 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.

Fonts

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

Map data

• OpenStreetMap® data of Helsinki, Joensuu, and other Finnish cities is open data, licensed under the Open Data Commons Open Database License (ODbL) by the OpenStreetMap Foundation (OSMF). OpenStreetMap data is © OpenStreetMap contributors.
• Elevation model (2 m) of Helsinki, Joensuu, and other Finnish cities is licensed under a Creative Commons Attribution 4.0 International License (CC-BY). Contains data from the National Land Survey of Finland Topographic Database 08/2016. Reference system is ETRS-TM35FIN. File format is ASCII Grid. Height system is N2000.
• Shuttle Radar Topography Mission (SRTM) data around Bolivian altiplano, Tallinn and elsewhere in the world between 56° S and 60° N is in the public domain. SRTM is a NASA (National Aeronautics and Space Administration) mission. SRTM data shipped with Ylikuutio belongs to SRTMGL3 dataset. Information about different SRTM datasets is available in OpenStreetMap Wiki.

Audio

• Arp Bass Loop 128 bpm.mp3 is made by JPMusic82 and it is licensed under the Creative Commons 0 (CC0 1.0) license.
• Blue Play is made by Greek555 and it is licensed under the Creative Commons 0 (CC0 1.0) license. Converted into OGG from the original 416882__greek555__blue-play.mp3.
• Chipland Loop (120 BPM-A Major) is made by SSS_Samples and and it is licensed under Creative Commons Attribution 3.0 Unported (CC BY 3.0) license.
• Dreaming Of Me is made by Greek555 and it is licensed under the Creative Commons 0 (CC0 1.0) license. Converted into OGG from the original 419588__greek555__dreaming-of-me.mp3.
• Sample 97 Bpm is made by Greek555 and it is licensed under the Creative Commons 0 (CC0 1.0) license.
• Tecno pop base and guitar 2 is made by frankum and it is licensed under the Creative Commons Attribution 3.0 Unported (CC BY 3.0) license. Original track by Frankum & Frankumjay. Converted into OGG from the original 395487__frankum__tecno-pop-base-and-guitar-2.mp3.

Trademarks

• Coverity® and Coverity Scan® are registered trademarks of Synopsys, Inc. in the US and/or other countries. See https://www.synopsys.com/company/legal/trademarks-brands.html.
• Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries. See https://www.linuxmark.org/programs/legal/trademark/attribution.
• Synopsys® is a registered trademark of Synopsys, Inc. in the US and/or other countries. See https://www.synopsys.com/company/legal/trademarks-brands.html.
• Windows is a trademark of Microsoft. See https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general.aspx.

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!