Teikitu: Real-Time Interactive Engine

A low-level real-time interactive engine written in C, and a game platform written in C++.
Explore Teikitu documentation »

Report bug · Request feature

Personal Project by Andrew Aye

Contact: GitHub, LinkedIn, Mail, Personal Page , Blog

Table of Contents

• Project Status
• Project History
• Author History
• Quick Start
• Repo Structure
• Prerequisites and Dependencies
• Known Issues and Workflow Improvements
• Copyright and license

Project Status

Internal Development Build Status

Build-Host-GPU-Audio-SIMD-Thread-OS-CPU	Continuous Integration and Testing
Ninja-WIN-None-None-C17-WIN-WIN-X64
Ninja-WIN-REF-None-C17-WIN-WIN-X64
Ninja-WIN-DX12-None-C17-WIN-WIN-X64
Ninja-WIN-VLKN-None-C17-WIN-WIN-X64
Xcode-MAC-None-None-C17-POSIX-POSIX-ARM
Xcode-MAC-Metal-None-C17-POSIX-POSIX-ARM
Make-LNX-None-None-C17-POSIX-POSIX-X64
Make-LNX-None-None-C17-POSIX-ADRD-ARM

NOTE: 10/14/2023: Metal, Vulkan, and Android are WIP. Once the work on the Physics Implementation is complete (tweaks to the integration with the parition manager for generating collision pairs), then the order of implementation will be Vulkan, Metal, Android, and then non-Desktop flavors of Apple.

Public Release Build Status

Build-Host-GPU-Audio-SIMD-Thread-OS-CPU	Continuous Integration and Testing
Ninja-WIN-None-None-C17-WIN-WIN-X64
Ninja-WIN-REF-None-C17-WIN-WIN-X64
Ninja-WIN-DX12-None-C17-WIN-WIN-X64
Xcode-MAC-None-None-C17-POSIX-POSIX-ARM
Make-LNX-None-None-C17-POSIX-POSIX-X64

Project History

I started this code base at the University of Waterloo (1993-2000). Since then, it has seen over eight significant refactors. The original implementation was object-oriented and Windows com-compliant. The current version is written in a functional style using C17. I am aware that there are many advantages to modern C++. However, when using C++, authors tend to adopt object-orientated paradigms, which, in my opinion, are not a good match for an engine. I have also found that the coding flexibility I adopt in coding this engine has crushed C++ compilers and optimizers. I once had a revision of the code base with the entire math and geometry library implemented as templates to facilitate an easy way to test 32bit and 64bit floats (for simulation issues and inconsistencies). The release build failed to finish after running for 24 hours. The current implementation, which uses the C pre-processor language for code generation to replace the use of templates, compiles in seconds (under a minute).

Author History

Andrew Aye has worked in the game industry since March 2001. His responsibilities were to create significant game engine features (for example, a modern simulation on the PS2) and then to create and modify all aspects of a game engine (real-time interactive). Along the way, he became responsible for growing other engineers and organizations. The highlight (to date) of this career was owning the responsibility for leading and managing two Call of Duty projects (Modern Warfare 3, and Ghosts). In 2017, he transitioned into a traditional tech company (Amazon) and helped to bootstrap the Amazon Pharmacy project. In his role on the leadership team of North America Consumables, he helped navigate the pandemic for the engineering teams (remote work) and collaborated on creative solutions for the excessive demand placed on the amazon.com site. He then spent a brief period in an SMS Ad startup (Attentive) as their first Senior Director to support their hyper-scale growth. He later transitioned to Meta in the Instagram Ads organization and, most recently, into the Developer Relations organization for Reality Labs.

Quick Start

Several quick start options are available:

• Tested (supported) generators are Visual Studio 2022, Xcode, Unix Makefiles, Ninja (Windows)
• Teikitu currently uses the superbuild process using CMake
  • The root CMakeLists.txt file contains only a list of external projects (including Teikitu)
  • Most of the projects are Teikitu dependencies
  • Once all the projects have been successfully built and installed, you can iterate only on Teikitu (or your personal project) without running cmake on the root.
• On a Windows host computer, clone the repo: git clone https://github.com/aaye/teikitu_release.git
  • Create a Visual Studio solution using the MSVC compiler and a project using LLVM and Clang
    • Iterating is faster with the Visual Studio solution/project. However, it is not an approved build format since we are forced to use the C++ compiler.
    • cd build_scripts (or equivalent)
    • .\make_windows.ps1 -GPU:DX12
    • Visual Studio solution file will be in //build/msvc17_msvc_c17_x64_win_win_desktop_dx12_none
    • Ninja Clang project will be in //build/msvc17_msvc_c17_x64_win_win_desktop_dx12_none
  • Compile the matrix of supported configurations
    • cd build_scripts (or equivalent)
    • .\test_windows.ps1
    • Build results will be in //build/ninja_xxx
• On a Mac host computer (preferably Apple hardware / ARM), clone the repo: git clone https://github.com/aaye/teikitu_release.git
  • Work in Progress Tested - Issue for script to automate the process
• On a Linux host computer, clone the repo: git clone https://github.com/aaye/teikitu_release.git
  • Work in Progress Tested on WSL (Windows Linux Environment) - Issue for script to automate the process

Repo Structure

teikitu
├──build_scripts/ - START HERE - contains scripts for creating IDE project files or building the project.
├──cmake/ - the core cmake files.
├──teikitu_assets/ - location is created during the build process to store reference data assets.
│  ├──images/ - contains reference images used in the unit tests.
├──teikitu_external/ - location for external dependencies.
├──teikitu_ide/ - contains files needed when generating ide specific project files.
├──teikitu_private/ - contains the source code for the project, including the unit tests.
│  ├──src/ - contains the source code of the project.
│  └──tests/ - contains the unit tests for validating the project.
├──teikitu_samples/ - contains some basic games and applications using Teikitu.
├──teikitu_sdk/ - contains the public include and inline files for using Teikitu.
└──teikitu_tools/ - contains some basic tools created to work with Teikitu.

Prerequisites and Dependencies

Used in the compilation process and will need to be installed on the host computer. I used chocolate.

• cmake – Open-Source, cross-platform build tool.
  • I keep a personal git fork to control the intermediate directory on MSVC projects.
• Ninja - Preferred build manager on Windows.
• LLVM - Preferred compiler including Windows.
• Flex Bison - Required for Doxygen. Only Windows version is no longer supported.
• Python 3.x - Used by OpenSubDiv and OpenUSD.
  • Installed with pip3: Jinga2, PyOpenGL, PySide6 (or PySide2).
  • It should be noted that getting either Pyside on Windows is difficult.
    This worked: pip3 install pyside6==6.5.1.1 --ignore-installed

The following projects are cloned, built, and installed in the teikitu_external folder.

• MiMalloc, TIFF, ZLIB, ZStd, LibDeflate, Directx-Headers, OneAPI, Boost, GLFW, OpenEXR, OpenSubDiv, OpenUSD, Iconv, Doxygen

The following projects are downloaded and used in place.

• Teikitu Asset Library, DirectX Agile SDK

Known Issues and Workflow Improvements

1. Microsoft Visual Studio Compiler (only) will compile all files as CXX

2. Standard atomic header for the Microsoft Visual Studio Compiler

The header file has an error in its 16-byte template overrides. I fixed the defect and validated the change by both the removal of a deadlock that the locking version created and by a size comparison of the atomic 16-byte data structures. If it is not using the 16-byte CAS instructions, the structure will pad to 32 bytes instead of 16. The corrected file was placed into the Teikitu external directory and is used instead of the standard (included) file.

3. Microsoft Visual Studio Clang-CL (no longer supported)

C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VC\v170\Microsoft.Cpp.ClangCl.Common.targets updated to prevent a Clang warning-as-error issue. If EnableFiberSafeOptimizations is enabled (/GT on the command line) it causes Clang-CL to issue a warning about an unused command-line argument. I suggest adding the following after a similar block that is used to clear out Multiprocessor Compilation (/MP)

<!-- copy EnableFiberSafeOptimizations to _EnableFiberSafeOptimizations.
     EnableFiberSafeOptimizations is cleared to avoid passing /GT to clang-cl, which generates a warning -->

<ItemGroup>
  <ClCompile Condition="'%(ClCompile.EnableFiberSafeOptimizations)' == 'true'">
    <_EnableFiberSafeOptimizations>true</_EnableFiberSafeOptimizations>
    <EnableFiberSafeOptimizations>false</EnableFiberSafeOptimizations>
  </ClCompile>`<br>
</ItemGroup>`

C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VC\v170\Microsoft.Cpp.ClangCl.Common.targets updated to prevent a critical issue where Clang-CL is not passing through the C-standard flag to Clang. The result caused PCH and compilation mis-matches (the PCH was not compiled using the same C-standard flags as the C source files).

Object created near line 132 () Missing an assignment for

LanguageStandard_C =“%(ClCompile.LanguageStandard_C)”

4. CMake Improvements when generating Visual Studio project files. (Personal preference change, not necessary by others)

Modified to allow me to set the intermediate directory.

5. CMake breaks C-only projects through injection of a C++ ForceLinkerLanguage file.

I could only modify the code responsible for injecting this file (CMake source, not in CMake files). It is unclear by the way they inject it if the file is ever correctly configured for the project context. In any case, I found multiple points of breakage with various files in the system include chain due to this injection and my specific project context. After configuration, the manual way to deal with the issue is to go into the XCode project and manually delete all of the CMakeCForceLinker files. I have done this and can confirm that the manual process will also work.

Copyright and License

Teikitu is subject to the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License unless otherwise stated.