Central singleton context for the libultraship engine. More...

#include <Context.h>

Inheritance diagram for Ship::Context:

Collaboration diagram for Ship::Context:

Public Member Functions
	Context (std::string name, std::string shortName)
	Constructs a Context with the given identifiers but does not initialize subsystems.

	~Context ()

const std::string &	GetShortName () const
	Returns the short application identifier.

TickableList &	GetTickableComponents ()

const TickableList &	GetTickableComponents () const

double	GetElapsedTimeSeconds () const
	Returns elapsed time in seconds since this Context was initialized.

void	UpdateElapsedTimeSeconds ()
	Recomputes elapsed time in seconds since this Context was initialized.

void	Tick (EventID eventId)
	Drives one frame of all registered TickableComponents for a specific EventID.

void	Tick ()
	Runs the default frame sequence: Update, LateUpdate, then Draw.

Public Member Functions inherited from Ship::Component
	Component (const std::string &name, std::shared_ptr< Context > context=nullptr)
	Constructs a Component with the given name.

virtual	~Component ()

void	Init (const nlohmann::json &initArgs=nlohmann::json::object())
	Performs one-time initialization of this component.

bool	IsInitialized () const
	Returns true once Init() (or MarkInitialized()) has completed successfully.

const std::string &	GetName () const
	Returns the name of this Component.

std::string	ToString () const
	Returns a human-readable string representation (e.g. "Name (id)").

std::string	ToTreeString (int depth=0) const
	Returns a human-readable tree representation of this component and its children.

	operator std::string () const
	Conversion operator to std::string; equivalent to ToString().

ParentComponentList &	GetParents ()
	Returns a mutable reference to the parent list.

const ParentComponentList &	GetParents () const
	Returns a const reference to the parent list.

ComponentList &	GetChildren ()
	Returns a mutable reference to the child list.

const ComponentList &	GetChildren () const
	Returns a const reference to the child list.

virtual std::shared_ptr< Component >	TryGetSharedComponent () noexcept
	Returns a shared_ptr to this Component when available, otherwise nullptr.

virtual std::shared_ptr< Component >	GetSharedComponent ()
	Returns a shared_ptr to this Component via the correct enable_shared_from_this base.

template<typename T >
bool	HasInChildren () const
	Checks whether any descendant Component matches type T via BFS.

template<typename T >
std::shared_ptr< T >	GetFirstInChildren () const
	Returns the first descendant that matches type T via BFS.

template<typename T >
std::shared_ptr< std::vector< std::shared_ptr< T > > >	GetInChildren () const
	Returns all descendants that match type T via BFS.

template<typename T >
bool	HasInParents () const
	Checks whether any ancestor Component matches type T via BFS.

template<typename T >
std::shared_ptr< T >	GetFirstInParents () const
	Returns the first ancestor that matches type T via BFS.

template<typename T >
std::shared_ptr< std::vector< std::shared_ptr< T > > >	GetInParents () const
	Returns all ancestors that match type T via BFS.

Public Member Functions inherited from Ship::Part
	Part ()
	Constructs a Part and assigns it a unique ID.

	Part (std::shared_ptr< Context > context)
	Constructs a Part with an explicit Context reference and unique ID.

virtual	~Part ()=default

uint64_t	GetId () const
	Returns the unique identifier for this Part.

bool	operator== (const Part &other) const
	Compares two Parts for equality by their unique IDs.

std::shared_ptr< Context >	GetContext () const
	Returns the Context this Part belongs to, or nullptr if unset.

void	SetContext (std::shared_ptr< Context > ctx)
	Sets the Context this Part belongs to.

Static Public Member Functions
static std::shared_ptr< Context >	CreateDefaultInstance (const std::string &name, const std::string &shortName, const std::string &configFilePath, const std::vector< std::string > &archivePaths={}, const std::unordered_set< uint32_t > &validHashes={}, uint32_t reservedThreadCount=1, AudioSettings audioSettings={}, std::shared_ptr< Component > window=nullptr, std::shared_ptr< Component > controlDeck=nullptr)
	Creates and stores the global Context instance with the default set of components.

static std::shared_ptr< Context >	CreateInstance (const std::string &name, const std::string &shortName)
	Creates and stores the global Context instance without adding any default components.

static std::shared_ptr< Context >	CreateInstance (const std::string &name, const std::string &shortName, std::vector< std::shared_ptr< Component > > components)
	Creates and stores the global Context instance with the given set of components.

static std::string	GetAppBundlePath ()
	Returns the platform-specific application bundle directory (e.g. the .app bundle on macOS).

static std::string	GetAppDirectoryPath (const std::string &appName="")
	Returns the platform-specific directory where the application stores its data.

static std::string	GetPathRelativeToAppDirectory (const std::string &path, const std::string &appName="")
	Resolves a path relative to the application data directory.

static std::string	GetPathRelativeToAppBundle (const std::string &path)
	Resolves a path relative to the application bundle directory.

static std::string	LocateFileAcrossAppDirs (const std::string &path, const std::string &appName="")
	Searches common application directories for a file and returns its absolute path.

Protected Member Functions
	Context ()=default

Protected Member Functions inherited from Ship::Component
virtual void	OnInit (const nlohmann::json &initArgs=nlohmann::json::object())
	Override this to implement component-specific initialization logic.

void	MarkInitialized ()
	Marks this component as initialized without going through Init().

template<typename T >
std::shared_ptr< T >	RequireDependency (const std::shared_ptr< T > &dependency, const std::string &dependencyName) const
	Returns a cached dependency after validating it exists and is initialized.

Protected Member Functions inherited from Ship::Part
virtual void	OnAdded (bool forced)
	Called after this Part has been added to a PartList.

virtual void	OnRemoved (bool forced)
	Called after this Part has been removed from a PartList.

Detailed Description

Central singleton context for the libultraship engine.

Context is the root Component that owns all subsystems as children. Consumers should create their own components and pass them in via GetChildren().Add(). Use CreateDefaultInstance() for a default set of components matching the original initialization order.

Subsystems are retrieved via GetChildren().GetFirst<T>().

Suggested future hierarchy changes (not yet implemented): The following reorganizations would better reflect logical ownership and reduce cross-component dependencies. Implementing them requires migrating call sites:

FileDrop → child of Window: file-drop events originate from the OS window; FileDrop has no reason to be a direct Context child.
ControlDeck → child of Window: game input is driven by and scoped to the active window surface. Moving it under Window makes the ownership clear.
Audio → child of Window: audio is part of the game presentation layer and logically belongs alongside the window.
Console → child of Window: the developer console is rendered inside the GUI layer (ConsoleWindow); placing Console under Window co-locates it with its presentation layer.

Constructor & Destructor Documentation

◆ Context() [1/2]

Ship::Context::Context	(	std::string	name,
		std::string	shortName
	)

Constructs a Context with the given identifiers but does not initialize subsystems.

Parameters

name	Human-readable application name.
shortName	Short application identifier.

◆ ~Context()

Ship::Context::~Context ( )

◆ Context() [2/2]

Ship::Context::Context ( )

protecteddefault

Member Function Documentation

◆ CreateDefaultInstance()

static std::shared_ptr< Context > Ship::Context::CreateDefaultInstance	(	const std::string &	name,
		const std::string &	shortName,
		const std::string &	configFilePath,
		const std::vector< std::string > &	archivePaths = `{}`,
		const std::unordered_set< uint32_t > &	validHashes = `{}`,
		uint32_t	reservedThreadCount = `1`,
		AudioSettings	audioSettings = `{}`,
		std::shared_ptr< Component >	window = `nullptr`,
		std::shared_ptr< Component >	controlDeck = `nullptr`
	)

static

Creates and stores the global Context instance with the default set of components.

This is the convenience factory that replicates the original initialization order: Logging, Config, ConsoleVariables, ThreadPool, Keystore, ResourceManager, ControlDeck, CrashHandler, Console, Window, Audio, Events, FileDrop, and ScriptLoader (if enabled).

All components are added to the hierarchy before any Init() is called. This ensures that every component can safely look up siblings during its own Init() without requiring a specific add-order dependency.

Init-order dependencies within this factory:

ResourceManager::Init() — ThreadPool must be present (it self-initializes on construction, so it is always ready).
Window construction/use — Config must be present and initialized before any Window code path reads persisted settings.
Audio construction/use — Config must be present and initialized before any Audio code path reads or writes persisted backend settings.
Config::Init(window) — Window must already be initialized before Config caches it for later validated use.

◆ CreateInstance() [1/2]

static std::shared_ptr< Context > Ship::Context::CreateInstance	(	const std::string &	name,
		const std::string &	shortName
	)

static

Creates and stores the global Context instance without adding any default components.

Consumers should add their own components via GetChildren().Add() after creation.

◆ CreateInstance() [2/2]

static std::shared_ptr< Context > Ship::Context::CreateInstance	(	const std::string &	name,
		const std::string &	shortName,
		std::vector< std::shared_ptr< Component > >	components
	)

static

Creates and stores the global Context instance with the given set of components.

Each component in components is added via GetChildren().Add() and then initialized by calling Component::Init() on it. Components should be provided in dependency order (e.g. Config before Window).

Parameters

name	Human-readable application name.
shortName	Short application identifier.
configFilePath	Path to the JSON configuration file.
components	Ordered list of components to add and initialize.

Returns: The newly created Context.

◆ GetAppBundlePath()

static std::string Ship::Context::GetAppBundlePath ( )

static

Returns the platform-specific application bundle directory (e.g. the .app bundle on macOS).

Returns: Absolute path string, or an empty string on platforms without the concept of a bundle.

◆ GetAppDirectoryPath()

static std::string Ship::Context::GetAppDirectoryPath ( const std::string & appName = "" )

static

Returns the platform-specific directory where the application stores its data.

Parameters

appName Override the application name used to build the path; defaults to the current app name.

Returns: Absolute path string.

◆ GetElapsedTimeSeconds()

double Ship::Context::GetElapsedTimeSeconds ( ) const

Returns elapsed time in seconds since this Context was initialized.

◆ GetPathRelativeToAppBundle()

static std::string Ship::Context::GetPathRelativeToAppBundle ( const std::string & path )

static

Resolves a path relative to the application bundle directory.

Parameters

path	Relative path to resolve.

Returns: Absolute path string.

◆ GetPathRelativeToAppDirectory()

static std::string Ship::Context::GetPathRelativeToAppDirectory	(	const std::string &	path,
		const std::string &	appName = `""`
	)

static

Resolves a path relative to the application data directory.

Parameters

path	Relative path to resolve.
appName	Override the application name used to build the base path.

Returns: Absolute path string.

◆ GetShortName()

const std::string & Ship::Context::GetShortName ( ) const

Returns the short application identifier.

◆ GetTickableComponents() [1/2]

TickableList & Ship::Context::GetTickableComponents ( )

◆ GetTickableComponents() [2/2]

const TickableList & Ship::Context::GetTickableComponents ( ) const

◆ LocateFileAcrossAppDirs()

static std::string Ship::Context::LocateFileAcrossAppDirs	(	const std::string &	path,
		const std::string &	appName = `""`
	)

static

Searches common application directories for a file and returns its absolute path.

Parameters

path	Filename or relative path to locate.
appName	Override the application name used to search.

Returns: Absolute path to the first match found, or an empty string if not found.

◆ Tick() [1/2]

void Ship::Context::Tick ( )

Runs the default frame sequence: Update, LateUpdate, then Draw.

Calls UpdateElapsedTimeSeconds() first, then dispatches Tick(Update), Tick(LateUpdate), and Tick(Draw).

◆ Tick() [2/2]

void Ship::Context::Tick ( EventID eventId )

Drives one frame of all registered TickableComponents for a specific EventID.

Runs all tickables in list order for the provided EventID only.

◆ UpdateElapsedTimeSeconds()

void Ship::Context::UpdateElapsedTimeSeconds ( )

Recomputes elapsed time in seconds since this Context was initialized.

The documentation for this class was generated from the following file:

include/ship/core/Context.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Context() [1/2]

◆ ~Context()

◆ Context() [2/2]

Member Function Documentation

◆ CreateDefaultInstance()

◆ CreateInstance() [1/2]

◆ CreateInstance() [2/2]

◆ GetAppBundlePath()

◆ GetAppDirectoryPath()

◆ GetElapsedTimeSeconds()

◆ GetPathRelativeToAppBundle()

◆ GetPathRelativeToAppDirectory()

◆ GetShortName()

◆ GetTickableComponents() [1/2]

◆ GetTickableComponents() [2/2]

◆ LocateFileAcrossAppDirs()

◆ Tick() [1/2]

◆ Tick() [2/2]

◆ UpdateElapsedTimeSeconds()