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-2023 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.
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 libxcursor-dev libxrandr-dev libxext-dev libxi-dev libxinerama-dev zlib1g-dev
Eg. with apt:
$ sudo apt install cmake build-essential libx11-dev libgl1-mesa-dev libglu1-mesa-dev libpng-dev libsdl2-dev libxcursor-dev libxrandr-dev libxext-dev libxi-dev libxinerama-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: google/googletest#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
, 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
> 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 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
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.
Q: Are there plans to support other graphics APIs? A: Vulkan will be supported in the future. Support for newer OpenGL versions needs to be considered.
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.
- 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).
- 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
Scene
s - 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 (Glyph
s) - 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
- 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.
- 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 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 originalhorse.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 originalporche_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 originalfreight.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 originalcat.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.
- 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 originalornage-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 originalpavers1b2.jpg
. License conditions are available on My Free Textures License/TOU page.
- kongtext font is made by codeman38, see res/fonts/kongtext/license.txt for the license.
- 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.
- 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
.
- 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.
- Antti Nuortimo (most of Ylikuutio code)
- Mikko Rasa (programming advice and bugfixes)
- Ronja Koistinen (support for building in a Podman container)
(found bugs and suggestions are very welcome!)
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!