Manages a prioritised collection of mounted Archive objects. More...

#include <ArchiveManager.h>

Inheritance diagram for Ship::ArchiveManager:

Collaboration diagram for Ship::ArchiveManager:

Public Member Functions
	ArchiveManager (std::shared_ptr< ResourceManager > resourceManager=nullptr, std::shared_ptr< Keystore > keystore=nullptr)

void	Init (const std::vector< std::string > &archivePaths)
	Discovers and mounts all archives found under the given paths.

void	Init (const std::vector< std::string > &archivePaths, const std::unordered_set< uint32_t > &validGameVersions)
	Discovers and mounts archives, filtering by acceptable game versions.

	~ArchiveManager ()

std::shared_ptr< Archive >	AddArchive (const std::string &archivePath)
	Opens and adds an archive by filesystem path.

std::shared_ptr< Archive >	AddArchive (std::shared_ptr< Archive > archive)
	Adds a pre-constructed Archive object to the managed collection.

std::shared_ptr< std::vector< std::shared_ptr< Archive > > >	GetArchives ()
	Returns all currently mounted archives in priority order (last = highest priority).

void	SetArchives (std::shared_ptr< std::vector< std::shared_ptr< Archive > > > archives)
	Replaces the entire archive list with a new collection.

size_t	RemoveArchive (std::shared_ptr< Archive > archive)
	Removes a specific archive from the managed collection.

size_t	RemoveArchive (const std::string &path)
	Removes the archive at the given filesystem path.

std::shared_ptr< File >	LoadFile (const std::string &filePath)
	Loads raw file bytes from the highest-priority archive that contains the path.

std::shared_ptr< File >	LoadFile (uint64_t hash)
	Loads raw file bytes by 64-bit hash from the highest-priority matching archive.

bool	WriteFile (std::shared_ptr< Archive > archive, const std::string &filename, const std::vector< uint8_t > &data)
	Writes raw data into a specific archive.

bool	HasFile (const std::string &filePath)
	Checks whether any mounted archive contains a file at the given path.

bool	HasFile (uint64_t hash)
	Checks whether any mounted archive contains a file with the given hash.

std::shared_ptr< Archive >	GetArchiveFromFile (const std::string &filePath)
	Returns the highest-priority archive that contains the given file.

std::shared_ptr< std::vector< std::string > >	ListFiles (const std::string &searchMask="")
	Lists virtual paths of all files matching the given search mask across all archives.

std::shared_ptr< std::vector< std::string > >	ListFiles (const std::list< std::string > &includes, const std::list< std::string > &excludes)
	Lists virtual paths matching include/exclude glob masks across all archives.

std::shared_ptr< std::vector< std::string > >	ListDirectories (const std::string &searchMask="")
	Lists virtual directory paths matching the given search mask across all archives.

std::vector< uint32_t >	GetGameVersions ()
	Returns the union of all game-version values found across mounted archives.

const std::string *	HashToString (uint64_t hash) const
	Looks up the virtual path string for a given 64-bit hash.

const char *	HashToCString (uint64_t hash) const
	Looks up the virtual path C-string for a given 64-bit hash.

bool	IsGameVersionValid (uint32_t gameVersion)
	Returns true if the given game version is in the set of valid versions.

void	SetUntrustedArchiveHandler (const UntrustedArchiveHandler &handler)
	Sets the callback invoked when an untrusted (unsigned/unknown-key) archive is added.

UntrustedArchiveHandler	GetUntrustedArchiveHandler () const
	Returns the current untrusted-archive handler.

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.

Protected Member Functions
void	AddGameVersion (uint32_t newGameVersion)
	Adds a game-version value to the internal version set.

void	ResetVirtualFileSystem ()
	Rebuilds the hash-to-path and path-to-archive lookup tables from the current archive list.

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.

Static Protected Member Functions
static std::vector< std::string >	GetArchiveListInPaths (const std::vector< std::string > &archivePaths)
	Scans the given filesystem paths and returns a flat list of archive file paths.

Detailed Description

Manages a prioritised collection of mounted Archive objects.

ArchiveManager presents a unified virtual filesystem over all mounted archives. When multiple archives contain a file with the same path, the archive added most recently (highest index) takes precedence, allowing "mod" archives to override base-game assets.

File lookups, directory listings, and game-version validation are all delegated here from the ResourceManager layer.

Required dependencies (constructor-injected):

ResourceManager — used by Archive objects during mount validation.
Keystore — used by Archive objects for signature validation.

Obtain the instance from Context::GetChildren().GetFirst<ResourceManager>()->GetArchiveManager().

Constructor & Destructor Documentation

◆ ArchiveManager()

Ship::ArchiveManager::ArchiveManager	(	std::shared_ptr< ResourceManager >	resourceManager = `nullptr`,
		std::shared_ptr< Keystore >	keystore = `nullptr`
	)

explicit

◆ ~ArchiveManager()

Ship::ArchiveManager::~ArchiveManager ( )

Member Function Documentation

◆ AddArchive() [1/2]

std::shared_ptr< Archive > Ship::ArchiveManager::AddArchive ( const std::string & archivePath )

Opens and adds an archive by filesystem path.

Parameters

archivePath Absolute or relative path to the archive file or directory.

Returns: Shared pointer to the newly added Archive, or nullptr on failure.

◆ AddArchive() [2/2]

std::shared_ptr< Archive > Ship::ArchiveManager::AddArchive ( std::shared_ptr< Archive > archive )

Adds a pre-constructed Archive object to the managed collection.

Parameters

archive Already-constructed (but not yet loaded) Archive.

Returns: Shared pointer to the added Archive.

◆ AddGameVersion()

void Ship::ArchiveManager::AddGameVersion ( uint32_t newGameVersion )

protected

Adds a game-version value to the internal version set.

◆ GetArchiveFromFile()

std::shared_ptr< Archive > Ship::ArchiveManager::GetArchiveFromFile ( const std::string & filePath )

Returns the highest-priority archive that contains the given file.

Parameters

filePath Virtual path of the file.

Returns: Shared pointer to the owning Archive, or nullptr if not found.

◆ GetArchiveListInPaths()

static std::vector< std::string > Ship::ArchiveManager::GetArchiveListInPaths ( const std::vector< std::string > & archivePaths )

staticprotected

Scans the given filesystem paths and returns a flat list of archive file paths.

Parameters

archivePaths Directories or explicit file paths to scan.

Returns: List of discovered archive file paths.

◆ GetArchives()

std::shared_ptr< std::vector< std::shared_ptr< Archive > > > Ship::ArchiveManager::GetArchives ( )

Returns all currently mounted archives in priority order (last = highest priority).

◆ GetGameVersions()

std::vector< uint32_t > Ship::ArchiveManager::GetGameVersions ( )

Returns the union of all game-version values found across mounted archives.

Returns: Vector of numeric game-version values.

◆ GetUntrustedArchiveHandler()

UntrustedArchiveHandler Ship::ArchiveManager::GetUntrustedArchiveHandler ( ) const

Returns the current untrusted-archive handler.

◆ HasFile() [1/2]

bool Ship::ArchiveManager::HasFile ( const std::string & filePath )

Checks whether any mounted archive contains a file at the given path.

Parameters

filePath Virtual path to check.

Returns: true if at least one archive has the file.

◆ HasFile() [2/2]

bool Ship::ArchiveManager::HasFile ( uint64_t hash )

Checks whether any mounted archive contains a file with the given hash.

Parameters

hash	64-bit hash of the file path.

Returns: true if at least one archive has the file.

◆ HashToCString()

const char * Ship::ArchiveManager::HashToCString ( uint64_t hash ) const

Looks up the virtual path C-string for a given 64-bit hash.

Parameters

hash	Hash to resolve.

Returns: C-string pointer, or nullptr if not found.

◆ HashToString()

const std::string * Ship::ArchiveManager::HashToString ( uint64_t hash ) const

Looks up the virtual path string for a given 64-bit hash.

Parameters

hash	Hash to resolve.

Returns: Pointer to the path string, or nullptr if the hash is not indexed.

◆ Init() [1/2]

void Ship::ArchiveManager::Init ( const std::vector< std::string > & archivePaths )

Discovers and mounts all archives found under the given paths.

Parameters

archivePaths Filesystem paths to archive files or directories to search.

◆ Init() [2/2]

void Ship::ArchiveManager::Init	(	const std::vector< std::string > &	archivePaths,
		const std::unordered_set< uint32_t > &	validGameVersions
	)

Discovers and mounts archives, filtering by acceptable game versions.

Parameters

archivePaths	Filesystem paths to archive files or directories.
validGameVersions	Set of game-version values to accept; others are rejected.

◆ IsGameVersionValid()

bool Ship::ArchiveManager::IsGameVersionValid ( uint32_t gameVersion )

Returns true if the given game version is in the set of valid versions.

Parameters

gameVersion Game version to validate.

◆ ListDirectories()

std::shared_ptr< std::vector< std::string > > Ship::ArchiveManager::ListDirectories ( const std::string & searchMask = "" )

Lists virtual directory paths matching the given search mask across all archives.

Parameters

searchMask Glob pattern (empty = list all directories).

Returns: Sorted, deduplicated list of matching directory paths.

◆ ListFiles() [1/2]

std::shared_ptr< std::vector< std::string > > Ship::ArchiveManager::ListFiles	(	const std::list< std::string > &	includes,
		const std::list< std::string > &	excludes
	)

Lists virtual paths matching include/exclude glob masks across all archives.

Parameters

includes	Paths must match at least one of these patterns.
excludes	Paths matching any of these patterns are removed from the result.

Returns: Sorted, deduplicated list of matching paths.

◆ ListFiles() [2/2]

std::shared_ptr< std::vector< std::string > > Ship::ArchiveManager::ListFiles ( const std::string & searchMask = "" )

Lists virtual paths of all files matching the given search mask across all archives.

Parameters

searchMask Glob pattern (empty = list everything).

Returns: Sorted, deduplicated list of matching paths.

◆ LoadFile() [1/2]

std::shared_ptr< File > Ship::ArchiveManager::LoadFile ( const std::string & filePath )

Loads raw file bytes from the highest-priority archive that contains the path.

Parameters

filePath Virtual path of the file.

Returns: Loaded File, or nullptr if no mounted archive contains the file.

◆ LoadFile() [2/2]

std::shared_ptr< File > Ship::ArchiveManager::LoadFile ( uint64_t hash )

Loads raw file bytes by 64-bit hash from the highest-priority matching archive.

Parameters

hash	CRC/hash of the file path.

Returns: Loaded File, or nullptr if not found.

◆ RemoveArchive() [1/2]

size_t Ship::ArchiveManager::RemoveArchive ( const std::string & path )

Removes the archive at the given filesystem path.

Parameters

path	Filesystem path of the archive to remove.

Returns: Number of archives removed (0 or 1).

◆ RemoveArchive() [2/2]

size_t Ship::ArchiveManager::RemoveArchive ( std::shared_ptr< Archive > archive )

Removes a specific archive from the managed collection.

Parameters

archive Archive to remove.

Returns: Number of archives removed (0 or 1).

◆ ResetVirtualFileSystem()

void Ship::ArchiveManager::ResetVirtualFileSystem ( )

protected

Rebuilds the hash-to-path and path-to-archive lookup tables from the current archive list.

◆ SetArchives()

void Ship::ArchiveManager::SetArchives ( std::shared_ptr< std::vector< std::shared_ptr< Archive > > > archives )

Replaces the entire archive list with a new collection.

Parameters

archives New ordered list of archives.

◆ SetUntrustedArchiveHandler()

void Ship::ArchiveManager::SetUntrustedArchiveHandler ( const UntrustedArchiveHandler & handler )

Sets the callback invoked when an untrusted (unsigned/unknown-key) archive is added.

Parameters

handler Callback; return true to accept, false to reject the archive.

◆ WriteFile()

bool Ship::ArchiveManager::WriteFile	(	std::shared_ptr< Archive >	archive,
		const std::string &	filename,
		const std::vector< uint8_t > &	data
	)

Writes raw data into a specific archive.

Parameters

archive	Target archive (must be mounted and writable).
filename	Virtual path to write to within the archive.
data	Raw bytes to write.

Returns: true on success.

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

include/ship/resource/archive/ArchiveManager.h

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ArchiveManager()

◆ ~ArchiveManager()

Member Function Documentation

◆ AddArchive() [1/2]

◆ AddArchive() [2/2]

◆ AddGameVersion()

◆ GetArchiveFromFile()

◆ GetArchiveListInPaths()

◆ GetArchives()

◆ GetGameVersions()

◆ GetUntrustedArchiveHandler()

◆ HasFile() [1/2]

◆ HasFile() [2/2]

◆ HashToCString()

◆ HashToString()

◆ Init() [1/2]

◆ Init() [2/2]

◆ IsGameVersionValid()

◆ ListDirectories()

◆ ListFiles() [1/2]

◆ ListFiles() [2/2]

◆ LoadFile() [1/2]

◆ LoadFile() [2/2]

◆ RemoveArchive() [1/2]

◆ RemoveArchive() [2/2]

◆ ResetVirtualFileSystem()

◆ SetArchives()

◆ SetUntrustedArchiveHandler()

◆ WriteFile()