Feel free to read the wiki to learn more about what's under the hood!
A fun project I came up with to get started with embedded programming on STM32 platform!
KrisRaycaster is a 3D raycasting renderer / game prototype built for STM32 microcontrollers.
- You can also run it in TouchGFX's simulator (Windows-only) or through SDL2 on any supported x86 platform (Windows, MacOS, Linux).
- Desktop build uses software rendering, which is quite slow on bigger resolutions, keep this in mind when considering performance.
Inspiration for the game are early 3D shooters, such as id Software's Wolfenstein 3D. These games were developed before the advent of dedicated graphics hardware, so all rendering was handled in software, drawing each pixel without the help of a modern graphics pipeline.
True 3D rendering without a GPU is quite slow, but ray casting is a very fast algorithm that could be easily used back then. It is considered 2.5D (pseudo-3D), since it simulates 3D visuals using a 2D map by casting a ray for every vertical slice of the screen until they hit a solid object. This creates an illusion of depth and perspective.
This project is educational in nature, and though it can be further optimized, my primary goal was to learn the ray casting technique and familiarize myself with the STM32 development ecosystem. It's rewarding to create visually appealing results on a platform with limited resources compared to modern handheld consoles.
I hope to inspire you to tinker and explore further on your own!
YouTube: 3D Raycaster Engine on STM32 | 1MB RAM, 60 FPS (STM32H750B-DK)
Tested on STM32H750-DK (480 MHz, 480x272 LCD-TFT, 1MB RAM, 128KB Flash). It also has DMA2D capabilities for HW acceleration.
I don't have access to any other boards, so support may vary.
Having a screen is certainly required, and also enough memory for framebuffers and texture atlas. If your board has less memory, you could try using a single buffer or lowering the resolution of the game.
- Open the
TouchGFXfolder insrc/stm32-touchgfxdirectory. - Open
KrisRaycaster.touchgfxand TouchGFX will automatically generate missing files (drivers, HAL, autogenerated files). - You can open the simulator build in
simulator/msvs/Application.vcxprojwith Visual Studio for faster development. - To flash the app on your board, open the project in TouchGFX Designer (you should see GameScreen) and flash it from there.
This project uses vcpkg package manager with ninja toolchain to manage dependencies (SDL2) and CMake as a build system.
If you have vcpkg installed already, you can use cmake profile vcpkg-system that will use global environment variable VCPKG_ROOT.
You can also use vcpkg-submodule to use vcpkg as git submodule. In this case, vcpkg will be downloaded in extern/vcpkg.
- If you're using the submodule, make sure to clone the repository with:
git clone --recursive. - If you have already cloned the project, run
git submodule update --recursive --remote.
CMake will be automatically run when using IDEs such as Visual Studio, VSCode (with CMake extensions) and CLion.
- You can also run it through console with
cmake --preset vcpkg-submoduleandcmake --build build.
If ninja is not installed, you will need to install it (e.g. choco install ninja) and make sure it's in the PATH.
You can install ninja with brew install ninja.
On Ubuntu, ninja is installed with sudo apt install ninja-build. If using another distribution, find the equivalent package.
You might need to add CMAKE_C_COMPILER and CMAKE_CXX_COMPILER to cacheVariables in CMakePresets.json, for example:
{
"version": 2,
"configurePresets": [
{
"name": "vcpkg-system",
"binaryDir": "${sourceDir}/build",
"generator": "Ninja",
"cacheVariables": {
"CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
"CMAKE_BUILD_TYPE": "Debug",
"CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
"CMAKE_C_COMPILER": "gcc",
"CMAKE_CXX_COMPILER": "g++"
}
}
]
}