Class Engine

Nested Relationships

Nested Types

Class Documentation

class Engine

Core engine systems singleton.

Public Types

enum class State

The current state of the engine.

Values:

enumerator Dead
enumerator Alive
enumerator Ready
enumerator Running

Public Functions

inline const InitConfig &GetInitConfig() const

Get an immutable reference to the initialization config values.

Returns:

The initialization config values

const std::filesystem::path GetDataDirectory()

Get a path to the data directory where logs and game data should be stored.

This path will be created if it does not exist when this function is called

Returns:

Data directory path

template<typename F, typename ...Args, typename R = std::invoke_result_t<F&&, Args&&...>>
inline std::shared_future<R> RunTaskOnMainThread(F func, Args... args)

Run a task on the main thread.

Warning

Since rendering happens on the main thread, excessive use of this method for other purposes may slow rendering performance

Parameters:

  • func – The task to execute

  • args – The arguments to the task function

Throws:

BadStateException – If the engine is not in the Running state

Returns:

A future that will be fulfilled when the task completes

void CoreInit(const InitConfig &initCfg)

Initialize all engine systems that don’t require graphics or windowing.

If the engine is not in standalone mode, this will also trigger bundle loading.

The engine must be in the Dead state when this method is called

void GfxInit()

Initialize the graphics backend and windowing system.

The engine must be in the Alive state when this method is called

void Run()

Perform any final pre-run tasks and start the game loop.

The engine must be in the Ready state when this method is called

void Quit()

Stop the game loop.

The engine must be in the Running state when this method is called

void GfxShutdown()

Shutdown windowing and graphics systems.

Any GPU resources still existing at this time will be destroyed via appropriate functions before shutdown

The engine must be in the Ready state when this method is called

void CoreShutdown()

Shutdown all engine systems that don’t require graphics or windowing.

After this function is called, the process may be safely exited or the engine may be re-initialized

The engine must be in the Alive state when this method is called

inline State GetState()

Get the current state of the engine.

Returns:

The engine state

Public Members

struct Cacao::Engine::Config config

Public Static Functions

static Engine &Get()

Get the instance and create one if there isn’t one.

Returns:

The instance

struct Config

Configuration values for the engine that may change at runtime.

Public Members

std::chrono::milliseconds fixedTickRate

The rate at which fixed ticks should occur, specified as the amount of time between fixed ticks in milliseconds.

int maxFrameLag

The number of frames the renderer can be behind before skipping some to catch up.

bool alwaysRerenderUI

Whether or not to always re-render the UI every frame. Useful for inspecting UI graphics calls in RenderDoc or similar.

struct InitConfig

Configuration values that are set for startup and cannot be modified afterwards.

Public Members

bool standalone

Whether the engine is running outside of a bundle.

If this flag is set, the engine will not attempt to validate that it is in a game bundle on startup. This will also disable all systems related to the default asset loader and bundle systems. Assets, worlds, and game modules will need to be manually loaded and configured in this mode.

std::string initialRequestedBackend

The requested backend to try to initialize first, overriding the default setting.

std::string preferredWindowProvider

The preferred windowing provider to use.

The available options are:

  • win32 Windows API (Windows only)

  • cocoa Cocoa (MacOS only)

  • x11 X11 via XCB (Linux only)

  • wayland Wayland (Linux only)

Note

If the provider requested is not available or this string is empty, default behavior will be used

bool suppressConsoleLogging

Whether or not to suppress console logging output.

bool suppressFileLogging

Whether or not to suppress file logging output.

ClientIdentity clientID

ID of the client application. This should be in reverse-domain format (e.g. com.example.MyGame), but this is not enforced.