A named Part with a parent/child hierarchy and optional thread safety. More...

#include <Component.h>

Inheritance diagram for Ship::Component:

Collaboration diagram for Ship::Component:

Public Member Functions
	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.

Protected Member Functions
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

A named Part with a parent/child hierarchy and optional thread safety.

Component extends Part with a human-readable name, a string representation, and bidirectional parent/child relationships managed via ComponentList. Adding a child automatically adds the corresponding parent, and vice versa. When the COMPONENT_THREAD_SAFE preprocessor flag is defined, all relationship mutations are guarded by a recursive_mutex held by the ComponentList (PartList).

Constructor & Destructor Documentation

◆ Component()

Ship::Component::Component	(	const std::string &	name,
		std::shared_ptr< Context >	context = `nullptr`
	)

explicit

Constructs a Component with the given name.

Parameters

name	A human-readable name for this Component.

◆ ~Component()

virtual Ship::Component::~Component ( )

virtual

Member Function Documentation

◆ GetChildren() [1/2]

ComponentList & Ship::Component::GetChildren ( )

Returns a mutable reference to the child list.

◆ GetChildren() [2/2]

const ComponentList & Ship::Component::GetChildren ( ) const

Returns a const reference to the child list.

◆ GetFirstInChildren()

template<typename T >

std::shared_ptr< T > Ship::Component::GetFirstInChildren ( ) const

Returns the first descendant that matches type T via BFS.

Template Parameters

T	The derived type to search for via dynamic_cast.

Returns: The first matching descendant, or nullptr if none found.

◆ GetFirstInParents()

template<typename T >

std::shared_ptr< T > Ship::Component::GetFirstInParents ( ) const

Returns the first ancestor that matches type T via BFS.

Template Parameters

T	The derived type to search for via dynamic_cast.

Returns: The first matching ancestor, or nullptr if none found.

◆ GetInChildren()

template<typename T >

std::shared_ptr< std::vector< std::shared_ptr< T > > > Ship::Component::GetInChildren ( ) const

Returns all descendants that match type T via BFS.

Template Parameters

T	The derived type to filter by via dynamic_cast.

Returns: A vector of all matching descendants.

◆ GetInParents()

template<typename T >

std::shared_ptr< std::vector< std::shared_ptr< T > > > Ship::Component::GetInParents ( ) const

Returns all ancestors that match type T via BFS.

Template Parameters

T	The derived type to filter by via dynamic_cast.

Returns: A vector of all matching ancestors.

◆ GetName()

const std::string & Ship::Component::GetName ( ) const

Returns the name of this Component.

◆ GetParents() [1/2]

ParentComponentList & Ship::Component::GetParents ( )

Returns a mutable reference to the parent list.

◆ GetParents() [2/2]

const ParentComponentList & Ship::Component::GetParents ( ) const

Returns a const reference to the parent list.

◆ GetSharedComponent()

virtual std::shared_ptr< Component > Ship::Component::GetSharedComponent ( )

virtual

Returns a shared_ptr to this Component via the correct enable_shared_from_this base.

Subclasses that inherit enable_shared_from_this via multiple paths (e.g. TickableComponent inherits from both Component and Tickable, each with their own enable_shared_from_this) must override this to use the base whose weak_ptr is properly initialized by make_shared.

◆ HasInChildren()

template<typename T >

bool Ship::Component::HasInChildren ( ) const

Checks whether any descendant Component matches type T via BFS.

Template Parameters

T	The derived type to search for via dynamic_cast.

Returns: True if at least one matching descendant is found.

◆ HasInParents()

template<typename T >

bool Ship::Component::HasInParents ( ) const

Checks whether any ancestor Component matches type T via BFS.

Template Parameters

T	The derived type to search for via dynamic_cast.

Returns: True if at least one matching ancestor is found.

◆ Init()

void Ship::Component::Init ( const nlohmann::json & initArgs = nlohmann::json::object() )

Performs one-time initialization of this component.

This method is non-virtual and manages the initialized state flag. It calls the protected virtual OnInit() hook exactly once; subsequent calls are no-ops.

Concrete subclasses that need parameter-free initialization should override OnInit() rather than Init().

Subclasses that require initialization parameters (e.g. ResourceManager) provide their own Init(…) overload and must call MarkInitialized() when initialization succeeds.

Parameters

initArgs Optional JSON object containing initialization arguments for this component. Passed through to OnInit().

◆ IsInitialized()

bool Ship::Component::IsInitialized ( ) const

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

Components that self-initialize in their constructor (e.g. Config, ThreadPool) call MarkInitialized() there and return true immediately. Components initialized via Init() / OnInit() return true only after that call succeeds.

◆ MarkInitialized()

void Ship::Component::MarkInitialized ( )

protected

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

Call this in the constructor of components that self-initialize (i.e. are fully usable as soon as they are constructed and need no separate Init() call), or at the end of a custom parameterized Init(…) override, so that IsInitialized() returns true and ordering-dependency checks pass.

◆ OnInit()

virtual void Ship::Component::OnInit ( const nlohmann::json & initArgs = nlohmann::json::object() )

protectedvirtual

Override this to implement component-specific initialization logic.

Called by Init() the first time it is invoked. After OnInit() returns without throwing, the component is marked as initialized. If OnInit() throws, the component remains uninitialized so Init() may be retried.

Parameters

initArgs JSON object with component-specific initialization arguments from the build hierarchy. Default implementation ignores them.

Components with initialization parameters (ResourceManager, Window, …) provide their own Init(…) overload instead of overriding this method.

The default implementation is a no-op.

Reimplemented in Ship::Logger, Ship::Gui, Ship::Window, Fast::Fast3dWindow, LUS::GfxDebuggerWindow, LUS::InputEditorWindow, Ship::Audio, Ship::Console, Ship::ResourceManager, Ship::ConsoleWindow, Ship::EventDebuggerWindow, Ship::GuiElement, Ship::StatsWindow, Ship::GameOverlay, Ship::GuiMenuBar, and Ship::GuiWindow.

◆ operator std::string()

Ship::Component::operator std::string ( ) const

explicit

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

◆ RequireDependency()

template<typename T >

std::shared_ptr< T > Ship::Component::RequireDependency	(	const std::shared_ptr< T > &	dependency,
		const std::string &	dependencyName
	)		const

protected

Returns a cached dependency after validating it exists and is initialized.

Use this from subclasses when accessing constructor- or init-cached component dependencies. The dependency must both exist and already be initialized.

Exceptions

std::runtime_error	if the dependency pointer is empty.
std::runtime_error	if the dependency exists but is not initialized.

◆ ToString()

std::string Ship::Component::ToString ( ) const

Returns a human-readable string representation (e.g. "Name (id)").

◆ ToTreeString()

std::string Ship::Component::ToTreeString ( int depth = 0 ) const

Returns a human-readable tree representation of this component and its children.

Parameters

depth Indentation depth (0 = root).

◆ TryGetSharedComponent()

virtual std::shared_ptr< Component > Ship::Component::TryGetSharedComponent ( )

virtualnoexcept

Returns a shared_ptr to this Component when available, otherwise nullptr.

This method is safe to call during teardown paths where shared ownership may no longer be established.

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

include/ship/core/Component.h

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Component()

◆ ~Component()

Member Function Documentation

◆ GetChildren() [1/2]

◆ GetChildren() [2/2]

◆ GetFirstInChildren()

◆ GetFirstInParents()

◆ GetInChildren()

◆ GetInParents()

◆ GetName()

◆ GetParents() [1/2]

◆ GetParents() [2/2]

◆ GetSharedComponent()

◆ HasInChildren()

◆ HasInParents()

◆ Init()

◆ IsInitialized()

◆ MarkInitialized()

◆ OnInit()

◆ operator std::string()

◆ RequireDependency()

◆ ToString()

◆ ToTreeString()

◆ TryGetSharedComponent()