Assets

Loading an image or a sound is slow; loading it twice is wasteful. An asset layer loads each file once and shares it.

The concept

Assets (textures, fonts, audio, animation data) are loaded by name and cached, so the second request for the same asset is a lookup. Components then hold a cheap reference or a path instead of a copy, and a scene file can store just the path.

Caching and sharing

If a hundred enemies use the same sprite sheet, loading it a hundred times wastes time and memory. A cache keyed by path returns the same loaded asset to everyone. Shared ownership means the asset stays alive while anything uses it and can be freed once nothing does.

Handles instead of data

Components that store the loaded data itself cannot be saved to a file, and are expensive to copy. Storing the path (or a small handle) keeps components light and saveable; a separate step later turns the path into the live resource. That resolve step is where a missing or broken file is detected and reported.

Loading cost

Decoding an image or sound, then uploading it to the GPU, can take milliseconds, enough to drop frames. Engines load at well-chosen moments (between levels, behind a loading screen) or in the background. Parameters that change the result, such as a font's pixel size, must be part of the cache key, since the same file at two sizes is two different assets.

How ASGE does it

AssetManager and AssetPool

asset::AssetManager is the one entry point. It is built over a VirtualFileSystem and owns a path-keyed AssetPool per asset type, each a cache of std::shared_ptr<Asset<T>>:

• GetImage, GetAudio, GetFrameTable by virtual path; GetFont by path and pixel height, since a font is baked at a size.
• GetTexture uploads an image to the GPU once, caches the ITexture by virtual path and keeps ownership; UnloadTexture drops it.
• Loads fail with a Result error when the path does not resolve through the VFS or the file cannot be decoded.

asge::game::asset::AssetManager assets( vfs );

auto image = assets.GetImage( "textures/hero.png" );   // Result<shared_ptr<Asset<Image>>>
auto again = assets.GetImage( "textures/hero.png" );   // cached: same asset, no second decode

Resolving components

A Sprite stores its m_VirtualPath and m_SourceRect; those are what round-trip through a scene file. Each frame ResolveAssets (called from Game::Render) turns the paths of sprites and animations back into live textures. A sprite's texture therefore points into the manager's cache and must not outlive it.

Spritesheets and animation clips

A FrameTable is a named sequence of source rects into a spritesheet, loaded from a small TOML file. A GridSpec describes a contiguous range of cells over a regular grid (row-major or column-major), and MakeGridFrames does the grid math. An optional frame_durations array gives frames their own display time.

See also

Source: Game/Assets/AssetManager.hpp, Game/Assets/AssetPool.hpp, Game/Assets/FrameTable.hpp. Texture demo · Animation demo