class `PackageManager`

Inherits: Module<PackageManager>

Handles loading, unloading and saving of packages.

Public

Methods

LoadOrGetPackage

UPtr<PackageReadLock> LoadOrGetPackage(const Path &packagePhysicalPath, const Path &virtualPathPrefix = Path::kBlank)

Loads a package from the provided on disk.

The package will remain loaded until explicitly unloaded via a call to Unload(). If you request a package that was previously loaded, the existing package will be returned.

packagePhysicalPath: Path on disk from where to load the package.
virtualPathPrefix: If non-empty, this path will be added as a prefix to all resources within the package, so they may be loaded using this path. (e.g. "/Game/Textures/" prefix path will allow loading of a resource within the package named "BrickAlbedo" via "/Game/Textures/BrickAlbedo" path). Provided virtual prefix path is ignored if the package is previously loaded.

Returns: Lock that can be used for accessing the newly or previously loaded package, if successful. Null otherwise. Lock must be kept alive as long as you are accessing the underlying package.

LoadPackages

void LoadPackages(const Path &folderPath, bool recursive = true, const Path &virtualPathPrefix = Path::kBlank, bool addSubFoldersToVirtualPath = true)

Loads all packages within the folder.

All loaded packages will remain loaded until explicitly unloaded via a call to Unload(). If a package is already loaded, no operation will be performed for that package.

folderPath: Path to the folder which to search for packages.
recursive: If true, child folders of will also be searched for packages to load.
virtualPathPrefix: If non-empty, this path will be added as a prefix to all resources within the package, so they may be loaded using this path. (e.g. "/Game/Textures/" prefix path will allow loading of a resource within the package named "BrickAlbedo" via "/Game/Textures/BrickAlbedo" path). Provided virtual prefix path is ignored if the package is previously loaded.
addSubFoldersToVirtualPath: If this is true, then any sub-folders found in will be appended to , for any resources in those folders. If false, all resources will be registered directly with virtual path, provided it is not empty.

SavePackage

UPtr<PackageWriteLock> SavePackage(const SPtr<Package> &package, const Path &destinationPath, const PackageManagerSavePackageOptions &options)

Saves a package to a provided location on disk.

package: Package to save.
destinationPath: Path (including file name) to save the package to.
options: Options to control the save process.

Returns: Write lock on the newly acquired package.

UnloadPackage

void UnloadPackage(const Path &packagePath)

Unloads a package at the specified path.

packagePath: Physical path to the package to unload.

ChangePhysicalPackagePath

void ChangePhysicalPackagePath(const PackageWriteLock &packageWriteLock, const Path &newPath)

Moves or renames an existing package to a new physical location while keeping all the package references intact.

packageWriteLock: Write lock for the package to update the physical path for.
newPath: New physical path for the package.

ChangeVirtualPackagePath

void ChangeVirtualPackagePath(const PackageWriteLock &packageWriteLock, const Path &newVirtualPathPrefix)

Changes the virtual paths for all the resources in the provided package.

You should call this if you want to change the virtual path prefix for a package, but also if any of the resource paths within the package change.

packageWriteLock: Write lock for the package to update the virtual path for.
newVirtualPathPrefix: New virtual path for the package.

SavePackageMetaData

bool SavePackageMetaData(const PackageWriteLock &packageWriteLock)

Updates meta-data of a previously saved package.

packageWriteLock: Write lock for the package to update the meta-data for.

Returns: True if no errors occurred during the process. False if errors occurred, or if the meta-data doesn't fit in the package, in which case you should re-attempt a full save.

AcquireReadLock

AcquirePackageLockResult AcquireReadLock(const Path &physicalPackagePath, const AcquirePackageReadLockOptions &options, UPtr<PackageReadLock> &outLock)

Attempts to lock a package for reading.

Locking the package before performing read operations ensures that the package is not modified or destroying while a read operation is in progress.

physicalPackagePath: Absolute path to the package to lock.
options: Options that control how is the lock acquired.
outLock: Acquired lock, if successful. Package will remain locked until this object goes out of scope.

Returns: Information if the lock was acquired or not.

AcquireWriteLock

AcquirePackageLockResult AcquireWriteLock(const Path &physicalPackagePath, const AcquirePackageWriteLockOptions &options, UPtr<PackageWriteLock> &outLock)

Attempts to lock a package for writing.

Locking the package before performing write operations ensures that any existing read or write operations are allowed to finish, and that any new read or write operations do not start until the write lock is released.

physicalPackagePath: Absolute path to the package to lock.
options: Options that control how is the lock acquired.
outLock: Acquired lock, if successful. Package will remain locked until this object goes out of scope.

Returns: Information if the lock was acquired or not.

TryResolvePhysicalResourcePath

TOptional<ResourcePackagePath> TryResolvePhysicalResourcePath(const Path &physicalResourcePath) const

Resolves a physical path to a resource into a physical path to the package, and a path to the resource within the package.

physicalResourcePath: Physical path to the resource in the package, e.g. 'D:/path/to/package.b3d/path/to/resource'. Must be absolute.

Returns: If the provided path is valid, returns a structure with a physical path to the package, and path to the resource within that package. Returns null otherwise.

TryResolveVirtualResourcePath

TOptional<ResourcePackagePath> TryResolveVirtualResourcePath(const Path &virtualResourcePath) const

Resolves a virtual path to a resource into a physical path to the package, and a path to the resource within the package.

virtualResourcePath: Virtual path to the resource, e.g. '/game/textures/path/to/resource'.

Returns: If provided path can be resolved, returns a structure with a physical path to the package, and path to the resource within that package. Returns null otherwise.

TryGetPackagePathForResource

TOptional<Path> TryGetPackagePathForResource(const UUID &resourceId)

Attempts to retrieve a path to the package the resource is located in.

resourceId: ID of the resource.

Returns: Path to the package if the resource was located, or null otherwise.

GetResourceMetaData

SPtr<const PackageResourceMetaData> GetResourceMetaData(const UUID &resourceId)

Retrieves resource meta-data from the associated (previously loaded) package.

Returns null if resource cannot be found.

staticInstance

static T &Instance()

Returns a reference to the module instance.

Module has to have been started up first otherwise an exception will be thrown.

staticInstancePtr

static T *InstancePtr()

Returns a pointer to the module instance.

Module has to have been started up first otherwise an exception will be thrown.

staticShutDown

static void ShutDown()

Shuts down this module and frees any resources it is using.

staticIsStarted

static bool IsStarted()

Query if the module has been started.

Protected

Methods

~Module<T>

virtual ~Module<T>() = default

OnStartUp

virtual void OnStartUp()

Override if you want your module to be notified once it has been constructed and started.

OnShutDown

virtual void OnShutDown()

Override if you want your module to be notified just before it is deleted.

staticInstanceInternal

static T *&InstanceInternal()

Returns a singleton instance of this module.

staticIsDestroyed

static bool &IsDestroyed()

Checks has the Module been shut down.

staticIsStartedUp

static bool &IsStartedUp()

Checks has the Module been started up.

Private

Methods

LoadPackageResourceInformation

void LoadPackageResourceInformation(Package &package, const Path &physicalPackagePath, const Path &virtualPathPrefix)

Registers all required resource path/id mappings for all resources in the package.

Package read or write lock must be acquired, and package manager mutex must be locked by the caller.

ClearPackageResourceInformation

void ClearPackageResourceInformation(Package &package, const Path &virtualPathPrefix)

Clears all resource path/id mappings for all resources in the package.

Package read or write lock must be acquired, and package manager mutex must be locked by the caller.

Fields

mPackagesByPath

UnorderedMap<Path, SPtr<RuntimePackageInformation>> mPackagesByPath

mPackagesById

UnorderedMap<UUID, RuntimePackageInformation *> mPackagesById

mResourceIdToPackageId

UnorderedMap<UUID, UUID> mResourceIdToPackageId

mVirtualPathToResourcePackagePath

UnorderedMap<Path, ResourcePackagePath> mVirtualPathToResourcePackagePath

mMutex

Mutex mMutex