Tsar Game Engine

A Modern, Powerful, and Versatile C++ Game Engine

Welcome to Tsar, a modern, powerful, and versatile C++ game engine designed to bring your creative visions to life. While we recognize that we can't yet compete with giants like Unreal Engine or Unity, our goal is to combine the best aspects of these engines with unique innovations of our own—elements we believe are missing from the current landscape.

Tsar is built with the latest C++20 standards and leverages Vulkan 1.4 for high-performance rendering, among other cutting-edge technologies. Our aim is to create a tool that feels familiar to developers experienced with Unreal or Unity, allowing them to transition seamlessly while benefiting from a modern architecture that pushes the boundaries of what’s possible. Tsar aspires to be the Unreal Engine 2.0, reimagined with the latest advancements and built for the future.

Whether you're a beginner or an experienced developer, Tsar provides the tools and flexibility you need to create stunning games.

🚀 Features

• Modern C++20: Built with the latest C++20 standards, ensuring clean, efficient, and maintainable code.
• Vulkan 1.4 Rendering: High-performance graphics rendering using Vulkan, providing low-level access and control over the GPU.
• C++ Scripting: Custom scripting with a powerful reflection system using the RTTR library.
• Editor UI with ImGui: Intuitive and responsive user interface for the editor, powered by ImGui.
• Audio with miniaudio: High-quality, cross-platform audio playback and control with miniaudio.
• 2D Physics with Box2D: Fast, reliable, and highly accurate 2D physics simulations with Box2D.
• Cross-Platform (Windows for now, Linux support coming soon): Development on Windows with plans to extend support to Linux.
• YAML-based Serialization: Efficient and human-readable serialization using yaml-cpp.
• Logging with spdlog: High-performance, thread-safe logging using spdlog.
• Windowing with GLFW: Flexible and multi-platform windowing and input system.

🎮 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Vulkan: Required for rendering. Version 1.4 is recommended
• Visual Studio: Our main IDE for development. Visual Studio 22 is recommended
• Python: Required for build scripts and certain tools. Python 3.12+ is recommended
• PyYAML: Required for build scripts and certain tools.
• Git: For version control and cloning the repository.

Installation

1. Clone the Repository

   git clone --recursive https://github.com/EmberEyeStudio/Tsar-Game-Engine
   

   If you're an active developer, you may want to clone the dev branch directly:

   git clone --recursive -b dev https://github.com/EmberEyeStudio/Tsar-Game-Engine
   

2. Generate Project Files
   Execute the following script to install Tsar global variables:

  scripts/Install.py

Execute the following script to generate the Visual Studio project files:

  scripts/Gen-Projects.py

3. Open the Solution
   Open Tsar.sln in Visual Studio 2022.

4. Build the Engine
   Set the build configuration to Debug or Release and build the solution.

5. Run the Editor
   Once built, you can run the editor directly from Visual Studio.

🛠️ Usage

Tsar is designed to be intuitive and easy to use. You can start by creating a new project from the editor or open an existing one. The editor provides a visual interface for designing scenes, scripting behaviors, and configuring game settings.

For more detailed usage instructions, check out our Documentation.

We welcome contributions from the community! To get started, check out our Contributing Guidelines. Whether you're fixing bugs, improving documentation, or adding new features, your help is appreciated.

👥 Meet the Team

Our team is composed of talented and passionate individuals who bring their unique skills and perspectives to the development of Tsar.

• Dzhan (Wizendraw)
  Dzhan is an avid technologist with a deep love for audio engineering and physics. His creative problem-solving skills and attention to detail have made him an invaluable member of the Tsar team.

• Mustafa (CreatorInDeep)
  Mustafa is a versatile developer with a passion for creating cutting-edge technology. His curiosity and drive for innovation push the boundaries of what's possible in game development. When he's not coding, Mustafa loves diving into complex systems and experimenting with new tools and languages.

We are a small but dedicated team, constantly working to improve Tsar and make it the best engine it can be. We believe in continuous learning and innovation, and we're excited to share our journey with the community.

Follow us on
Twitter | Discord | YouTube

ECS

ECS (Entity Component System) is a data-oriented design which binds together everything in Tsar. It gives precise control over every game object and allows creating scalable systems thanks to its high-performance nature.

The Transform class is a component in the Tsar engine used to manage an object's position, rotation, and scale in 3D space.

Class Declaration

class Transform : public Component

This class inherits from the Component class and adds functionality related to transformation in 3D space. It uses the RTTR library for reflection.

Public Methods

Translation

• glm::vec3 GetTranslation()

  Returns the current translation (position) of the object as a glm::vec3.

• void SetTranslation(const glm::vec3& translation)

  Sets the object's translation using the provided glm::vec3.

Rotation

• glm::vec3 GetRotation()

  Returns the current rotation of the object as a glm::vec3.

• void SetRotation(const glm::vec3& rotation)

  Sets the object's rotation using the provided glm::vec3.

Scale

• glm::vec3 GetScale()

  Returns the current scale of the object as a glm::vec3.

• void SetScale(const glm::vec3& scale)

  Sets the object's scale using the provided glm::vec3.

Properties

The Transform class exposes three properties that can be accessed via getter and setter functions:

• glm::vec3 Translation

  • Get: GetTranslation()
  • Set: SetTranslation()

• glm::vec3 Rotation

  • Get: GetRotation()
  • Set: SetRotation()

• glm::vec3 Scale

  • Get: GetScale()
  • Set: SetScale()

These properties allow users to manipulate the position, rotation, and scale of the object in a more intuitive manner.

Scripting

Tsar uses C++ as scripting language to benefit from its unmatched speed and versatility as its the best OOP language.
Writing scripts is essential for creating immersive and complex games. All of your game logic will be modeled by your scripts.
For this reason our scripting interface is focused on simplicity.

Here's an example NPC logic script:

How to create a script

TsarEd\assets\scripts\GenProject.py

You should now have a default Sandbox solution
All script classes must be created in TsarScript namespace.

Using Editor

Soon to be supported!

Using Visual Studio

MyExampleClass.hxx

#include "ScriptEngine.hxx"

namespace TsarScript
{
   TClass()
   class MyExampleClass : public Entity
   {
       TFunc()
       void SomePrintFunc();
   };

   TClass()
   class MyPlayer : public Entity
   {
   GENERATE_BODY()

   private: 
       TFunc()
       void Start();

       TFunc()
       void Update(float dt);
   };
}

Change MyExampleClass with your script/class name, you can have as many classes you want in single header.
TClass() is used for Reflection so Tsar and your classes can work together.

3. In source file(.cxx) include your header and define your functions:

MyExampleClass.cxx

#include "MyExampleClass.hxx"

#include "scripting/Input.hxx" //for MyPlayer input

#include "scripting/Debug.hxx" //for MyClassExample

namespace TsarScript
{
   void MyClassExample::SomePrintFunc()
   {
       Debug::LogInfo("something happened");
   }

   void MyPlayer::Start()
   {

   }

   void MyPlayer::Update(float dt)
   {
       if (Input::GetKeyPressed(KeyCode::T))
       {
   	    std::cout << m_Entity.GetName() << '\n';
       }
   }
}

Adding Functions/Methods

Normal functions are your typical C++ methods, which Tsar knows nothing about.

void MyFunction(); // No engine context here

If you need your function to be seen by Tsar you should use Reflective functions/methods, which are declared with TFunc() before them like this:

TFunc()
void MyFunction(); // Can use engine functionality

If your function should access anything from Tsar, like components, scripts, assets you must define your function with TFunc().
If the function is purely C++ logic, you don’t need TFunc().

Adding Properties

TClass();
class DumbAI : public Entity
{
public:
	AudioSource m_BigSwing; //Not seen in Editor
};

Written like that AudioSource cannot be assigned/referenced/modified from Editor.

If you want to expose the Property to Editor use TProperty() before declaration.

TClass();
class DumbAI : public Entity
{
public:
    TProperty();
	AudioSource m_BigSwing; //Modifiable in Editor
};

Audio System

Tsar’s audio features include full 3D spatial sound, real-time mixing and predefined effects.
Read this section to learn about audio in Tsar, including:

• Audio Engine
• Audio Clips
• Audio Sources
• Audio Listeners
• Audio Settings
• Audio Mixing
• Audio Capture

Audio Engine - purpose, graph explanation, supported formats, windows events

Audio Source - purpose, graph node, functionality(Editor, Runtime diff)

• asset integration
• effects
• list other properties

Audio Listener - purpose, functionality, settings

Audio Engine

The audio engine is an interface which allows control over handful of features such as:

• Master Volume
• Pitch
• Panning control
• 3D spatial sound
• Audio playback (WAV, MP3)
• Mixing multiple audio streams

Master Volume Control

Volume in Tsar is percent based, which means you can set it between 0(mute) and 1(Full volume).
You can set master volume in script using:

AudioListener listener = GetComponent<AudioListener>();
listener.SetVolume(0.8f); //Set master volume to 80%

There is only one listener per Scene!

3D Spatial Sound

Spatialization is based on both Listener and Audio Sources position and direction, for Listener it can be enabled/disabled using:

AudioListener listener = GetComponent<AudioListener>();
listener.EnableSpatialization(true);

You can switch between manual and automatic update of listener position & orientation.
By default they're updated automatically.

AudioListener listener = GetComponent<AudioListener>();
listener.EnableAutomaticUpdate(true);

If you disabled automatic update, you can update them manually:

AudioListener listener = GetComponent<AudioListener>();
listener.SetPosition({10.f, 10.f, 5.f}); //x=10, y=10, z=5
listener.SetDirection({1.f, 0.f, 0.f}); //facing Right along X, use normalized vector

Audio Playback

Tsar currently supports wav and mp3 audio files, also refered as audio clips.
In Editor, for now, you can only Play the clip in Audio Source without Pause, Resume, or any applied effects.
Applying effects works during Runtime.

Mixing

Mixing is currently not supported.

Audio Source Component

Each audio source is a node on a graph inside an Audio Engine. You can connect them however you like and apply different effects

Usage

Initialize

Add component AudioSourceComponent to your entity
Click 'Find' button and navigate to desired audio file

To access component data get the component inside scripting use:

AudioSource src = GetComponent<AudioSource>();

To have actual sound it needs an Audio Clip. You can assign one by Drag-n-Drop from Content Browser

Volume

void SetVolume(float volume, bool IsVolumeInDecibels = true);

AudioSource src = GetComponent<AudioSource>();
src.SetVolume(10.0f);   //Set volume of sound to 10 decibels
src.SetVolume(100.0f, false);  //Set linear volume of sound to 20 decibels.
//See linear to db conversion

void IncreaseVolume(float volumePercentIncrease, bool IsVolumeInDecibels = true);

AudioSource src = GetComponent<AudioSource>();
src.IncreaseVolume(10.0f);  //Increase current volume by 10% in decibels 10db->11db
src.IncreaseVolume(10.0f, false);   //Increase current volume by 10 decibels. 
//Doesn't scale linearly, see linear to db conversion

void DecreaseVolume(float volumePercentDecrease, bool IsVolumeInDecibels = true);

AudioSource src = GetComponent<AudioSource>();
src.DecreaseVolume(30.0f);  //Reduce current volume by 30%  10db->7db
src.DecreaseVolume(100.0f, false);   //Reduce current volume by 20db

Audio Source State

Audio Source has two states: Playing and Paused
Sounds also have cursor which shows the position at which we play the sound. Sound output always moves the cursor forwards.
Cursor position is always relative to start of the Audio Clip.

During Play the sound is producing output at its attached endpoint on the graph, if sound hasn't been attached manualy, it is directly producing output to Playback device through Audio Listener.

When sound enters Pause state its cursor is saved, so it can be seamlessly resumed later.

Below are methods which allow changing between the two states as well as modifying the cursor.
1000 miliseconds = 1 second

• Play
  
• PlayAt
  
• RewindTo
  
• RewindToSeconds
  
• Stop
  
• PauseAfter
  
• PauseAfterSeconds
  
• PauseFor
  
• PauseForSeconds
  

void Play();

Description

Play the sound from the beginning. Shift cursor at 0 and start output/playing.

Example:

AudioSource src = GetComponent<AudioSource>();
src.Play(); 

void PlayAt(u64 milisecondsFromStart);

Description

Set how many miliseconds from beginning to shift the cursor and start playing from there.

Example:

AudioSource src = GetComponent<AudioSource>();
src.PlayAt(1000);   //Go to 1 second and start playing
src.PlayAt(3500);   //Go to 3.5 second of clip and play sound

void RewindTo(u64 milisecondsFromStart, bool autoResume /*= true */);

Description

Similar to PlayAt(), but allows control over whether to start playing audio or simply move cursor.

Example:

AudioSource src = GetComponent<AudioSource>();
src.RewindTo(2500); //Resume playing back(or forward) to second 2.5 of the audio clip.
//Move cursor to second 2.5

Example:

AudioSource src = GetComponent<AudioSource>();
src.RewindTo(3000, false);  //Stop audio output. Cursor is at second 3.
//After starting the sound again, it will play from second 3. 

void RewindToSeconds(float secondsFromStart, bool autoResume /*= true */);

Description

Set how many seconds from beginning to shift the cursor and depending on autoResume

• true => start playing from there (default).
• false => stop playing sound.

Example:

AudioSource src = GetComponent<AudioSource>();
src.RewindToSeconds(5.0f, false);   //Stop output and move cursor to second 5
src.RewindToSeconds(4.0f);   //Move cursor to second 4 and start output/play sound

void Stop();

Description

Stop audio output immediatly. Switches to Pause state.

Example:

AudioSource src = GetComponent<AudioSource>();
src.Stop(); 

void PauseAfter(u64 pauseTimeInMiliseconds /* = 0u */);

Description

Set time in miliseconds after which the sound should Pause

Example:

AudioSource src = GetComponent<AudioSource>();
src.PauseAfter(1500);   //Continue playing for 1.5 seconds and then stop

void PauseAfterSeconds(float pauseTimeInSeconds /* = 0.0f */);

Description

Set time in seconds after which the sound should Pause

Example:

AudioSource src = GetComponent<AudioSource>();
src.PauseAfterSeconds(6.3f);    //Continue playing for 6.3 seconds and then stop

void PauseFor(u64 pauseTimeInMiliseconds /* = 0u */);

Description

Set time in miliseconds for which the sound should be Paused, after this time passes, sound starts playing again.

Example:

AudioSource src = GetComponent<AudioSource>();
src.PauseFor(2000); //Immediately pause the sound for 2 seconds, 
//after 2 seconds playing resumes

void PauseForSeconds(float pauseTimeInSeconds /* = 0.0f */);

Description

Set time in miliseconds for which the sound should be Paused, after this time passes, sound starts playing again.

Example:

AudioSource src = GetComponent<AudioSource>();
src.PauseForSeconds(4.0f);  //Immediately pause the sound for 4 seconds, 
//after 4 seconds playing resumes

Audio Source Effects

Audio Source supports these effects:

Pitch

Pitch makes a melody go higher or lower. Below are methods which can be used to change the pitch.

void SetPitch(float pitch);

Description Set the pitch by multiplying the current with given value.
resultPitch = currentPitch * pitch.

• ! pitch must be higher than 0

Example:

AudioSource src = GetComponent<AudioSource>();
src.SetPitch(1.5f); //Increase current pitch by 50%
src.SetPitch(0.4f); //Set pitch 40% of current(60% reduction)

void IncreasePitch(float increasePercentage);

Description

Increase pitch by given percentage.

Example:

AudioSource src = GetComponent<AudioSource>();
src.IncreasePitch(15.0f);   //Increase current pitch by 15%

void DecreasePitch(float decreasePercentage);

Description

Decrease pitch by given percentage.

Example:

AudioSource src = GetComponent<AudioSource>();
src.DecreasePitch(25.0f);   //Reduce current pitch by 25%

Doppler

The Doppler effect (also Doppler shift) is the change in the frequency of a wave in relation to an observer who is moving relative to the source of the wave. For example when a sportbike passes you by, you hear its 'pitch' change depending on its speed and distance. Wiki

void SetDopplerFactor(float dopplerFactor);

Description

Factor greater than 1 increases the effect and is suited for fast moving objects, factor less than 1 reduces the strength of the effect and better suited for slower objects.

Example:

AudioSource src = GetComponent<AudioSource>();
src.SetDopplerFactor(1.0f);   //Realistic Doppler effect based on physical laws
src.SetDopplerFactor(1.5f);   //Exaggerated effect, making pitch shift more pronounced
src.SetDopplerFactor(0.5f);   //Reduces the Doppler shift, making it more subtle

Spatialization

Listener is an abstraction for calculating sound in 3D space. As in real world, the sound gets attenuated when you go away from the source, this is achieved by setting the attenuation model, distance, gain and the cone of both AudioSource and AudioListener.

Attenuation Models

• AttenuationType::None - No distance attenuation and no spatialization
• AttenuationType::Reverse - Volume increases with distance
• AttenuationType::Linear - Linear decrease in volume, reaches zero at maxDistance
• AttenuationType::Exponential - Exponential decrease in volume, steeper falloff

void SetAttenuationModel(AttenuationType model);

Description

Change the attentuation type of AudioSource. What each model does is described above.

Example:

AudioSource src = GetComponent<AudioSource>();

src.SetAttenuationModel(AttenuationType::None); 

src.SetAttenuationModel(AttenuationType::Reverse);

src.SetAttenuationModel(AttenuationType::Linear);

src.SetAttenuationModel(AttenuationType::Exponential);

Attenuation Distance

In the calculation of attenuation, you can control the minimum and maximum distances for the attenuation calculation. This is useful if you want to ensure sounds don't drop below a certain volume after the listener moves further away and to have sounds play a maximum volume when the listener is within a certain distance.
minDistance defines distance from listener at which the sound is heard at full volume(or maxGain).
maxDistance defines distance from listener at which sound gets attenuated until fading out completely(or minGain).

  
                           minDistance                   maxDistance   
                                ↓                              ↓   
Distance ---------------------------------------------------------------------------------->   
Volume: |Full volume or maxGain | volume fades with distance   | no volume or minGain
   
                                |gain transition based on model|

void SetAttenuationDistance(float minDistance, float maxDistance);

Description

Set min and max distance for attenuation.

Example:

AudioSource src = GetComponent<AudioSource>();
src.SetAttenuationDistance(10.0f, 50.0f);   //Full volume(maxGain) within 10 meters,
//after 50 meters fades to minGain. Transition gain based on model for 10 to 50

void SetAttenuationDistanceMin(float minDistance);

Description

Set distance(between listener and source) after which attenuation is applied.

Example:

AudioSource src = GetComponent<AudioSource>();
src.SetAttenuationDistanceMin(15.0f);   //When listener is within 15 meters the sound 
// volume=maxGain(full volume by default), after that the sound start to fade out

void SetAttenuationDistanceMax(float maxDistance);

Description

Set max distance(between listener and source) in meters, after which, the sound fades out to minGain(no volume by default)

Example:

AudioSource src = GetComponent<AudioSource>();
src.SetAttenuationDistanceMax(30.0f);   //If distance to listener is >30 meters,
//sound is faded to minGain

Rolloff

To control how quickly a sound rolls off as it moves away from the listener, you need to configure the rolloff.
The distance is specified in Attenuation Distance

void SetRolloff(float rolloff);

Description

Multiply the current rolloff factor for fading of the sound in attenuation calculation.

Example:

AudioSource src = GetComponent<AudioSource>();
src.SetRolloff(2.0f);   //The sound attenuates more quickly(twice as fast), 
//meaning it will become quieter over a shorter distance

src.SetRolloff(0.5f);   //The sound attenuates slowly(two times slower), 
//meaning it will become quieter over a longer distance

Gain

The gain is the volume level that the sound can reach when applying distance attenuation or other gain-related effects.

gain = 0 → Mute

gain = 1 → Full volume

gain > 1 → Amplification. Using very high gain values (significantly above 1.0) can lead to clipping, if the resulting amplitude exceeds the maximum range of the audio format

void SetGain(float minGain, float maxGain);

Description

Set minimal gain for when source is outside of hearing range and max gain for when source is heard without attenuation.

Example:

AudioSource src = GetComponent<AudioSource>();
src.SetGain(0.1f, 0.8f);    //Limit sound volume between 10% & 80%

void SetGainMin(float minGain);

Description

Set min gain level for when sound is out of hearing range.

Example:

AudioSource src = GetComponent<AudioSource>();
src.SetGainMin(0.2f);  //Constraints to minimal volume reduction of 20%. 
//For example if audio is 10db, it cannot be reduced less than 2db

void SetGainMax(float maxGain);

Description

Set max gain level for when sound should be heard clearly without attenuation.

Example:

AudioSource src = GetComponent<AudioSource>();
src.SetGainMax(0.8f);   //Constraints to maximal volume amplification of 80%. 
//For example if audio is 10db, it cannot be amplified more than 8db.

Cone

The sound propagation is defined with a cone.
When the listener is inside the sound cone's inner angle (facing directly in front of the sound source), they hear the sound at full volume
If the listener is between the inner and outer angles, the sound transitions from full volume(1.0) to attenuated volume(outer gain) smoothly.
When the listener is outside the outer angle (to the sides or behind the sound source), the sound is attenuated (reduced) based on the outer gain.
See Direction

        Inner Cone       Transition Zone       Outer Cone
        Full Volume     Gradual Attenuation   Attenuated Volume
            /|\                 /|\               /|\
             |                   |                 |
      -------|-------------------|-----------------|-----------
      0°     | Inner Angle       | Outer Angle     | SILENCED AUDIO IS HERE

void SetConeF(float innerAngleInRadians, float outerAngleInRadians, float outerGain);

Description

Example:

AudioSource src = GetComponent<AudioSource>();
src.SetConeF(glm::radians(30.0f), glm::radians(120.0f), 0.4f);  
//Set sound to be attenuated to 40% of full volume if angle between listener and 
// sound is greater than 120 degrees

void SetCone(const glm::vec3& innerOuterGain);

Description

Convenience function, works same as SetConeF();
X : innerAngle(radians)
Y : outerAngle(radians)
Z : outerGain([0;1])

Example:

src.SetCone(glm::vec3{glm::radians(50.0f), glm::radians(140.0f), 0.2f}); 

//   |100% volume|   |transition|    |20% volume
// 0°|           |50°|          |140°|

Chapter 1

Animations