KernelAPI reference
Class AssetCache
Namespace: MicroEngine.Core
Assembly: MicroEngine.dll
Guide: Game lifecycle and time
Loads, shares and releases a game’s content files (Game.Assets): images as textures, packing tools’ atlases,
folders of images packed into one atlas, and TTF/OTF fonts. The same request returns the same object, so a texture
used by ten scenes is decoded and uploaded once, whichever scopes ask for it; an asset is disposed when the last scope
holding it releases it.
public sealed class AssetCache : IDisposableInheritance
Implements
Examples
var hero = Assets.Atlas("atlases/hero.json"); // TexturePacker or Aseprite JSON, Starling XMLvar sky = Assets.Texture("backgrounds/sky.jpg");var ui = Assets.Font("fonts/Inter-Regular.ttf");
using var level = Assets.CreateScope(); // released when the level endsvar tiles = level.Atlas("levels/forest/tiles.xml");Remarks
Paths are relative to the content source, with '/' separators, and must match the file names' letter case exactly on every system, because Linux, Android and browsers would not find "Hero.png" for "hero.png" even where Windows does. The content is a folder by default; the composition may name another source, such as a zip archive ([Content](/docs/api/microengine.hosting.hostbuilder/#MicroEngine_Hosting_HostBuilder_Content), [ZipContentSource](/docs/api/microengine.content.zipcontentsource/)).
Game.Assets lives as long as the game and is disposed after Unload. For assets of one level or scene,
create a child with [CreateScope](/docs/api/microengine.core.assetcache/#MicroEngine_Core_AssetCache_CreateScope_System_String_) and dispose it when the level ends. Scopes share: a scope that asks for
an asset another scope (a parent, a sibling) already loaded gets the same object instead of loading it again, and holds
it too; disposing a scope or calling [Unload](/docs/api/microengine.core.assetcache/#MicroEngine_Core_AssetCache_Unload_System_String_) releases its hold, and an asset is disposed when no scope
holds it any more. Loading belongs in Load, a scene's
Enter or a loading screen; a load during play is reported, because decoding a large image takes longer than a
frame. [Preload](/docs/api/microengine.core.assetcache/#MicroEngine_Core_AssetCache_Preload_System_String___) decodes on worker threads where the platform has them and uploads within a time budget
per frame, for loading screens.
The cache is built on the engine's asset store ([Store](/docs/api/microengine.core.assetcache/#MicroEngine_Core_AssetCache_Store)): every scope is an [AssetScope](/docs/api/microengine.content.assetscope/) ([Scope](/docs/api/microengine.core.assetcache/#MicroEngine_Core_AssetCache_Scope)), so typed handles ([Asset`1](/docs/api/microengine.content/)) and loaders of other kinds registered in [Loaders](/docs/api/microengine.core.assetcache/#MicroEngine_Core_AssetCache_Loaders) share the same lifetimes.
Constructors
AssetCache(IGraphicsDevice, string?)
Creates the root scope of a game’s assets.
public AssetCache(IGraphicsDevice device, string? root = null)Parameters
device IGraphicsDevice
Creates the textures.
root string?
The content folder; null for the composition’s (Content) or the Content folder next to the executable. It is opened on the first load, so games without content files never need one.
Properties
BackgroundDecoding
Whether Preload decodes on worker threads (true by default, except in browsers, where .NET runs on one thread and decoding happens within FrameBudgetMilliseconds instead).
public bool BackgroundDecoding { get; set; }Property Value
Content
The content folder files are read from (opened on first use).
public ContentFolder Content { get; }Property Value
Exceptions
The folder does not exist.
The content is not a folder (a zip archive, for example); use Source.
Count
How many assets this scope and its children hold: those they loaded and those they asked for that another scope (a parent included) had loaded, an asset several of them share counting once. On the root scope, every asset of the game. Allocates nothing, so it can be checked every frame.
public int Count { get; }Property Value
FrameBudgetMilliseconds
Time per frame Update spends finishing preloaded assets (decoding where needed, uploading), in milliseconds; at least one asset finishes per frame.
public double FrameBudgetMilliseconds { get; set; }Property Value
Loaded
The assets of this scope and its children, each once, in the order each scope asked for them.
public IReadOnlyList<AssetInfo> Loaded { get; }Property Value
Loaders
The loaders of the store, one per kind: “texture”, “atlas”, “folder atlas”, “font”, “sound”, “music” and any a game registers.
public AssetLoaderRegistry Loaders { get; }Property Value
Name
The scope’s name for diagnostics (null for the root and unnamed scopes).
public string? Name { get; }Property Value
Playing
Whether the game is past its first update; loads from then on count as loads during play (DuringPlay). The engine sets it.
public bool Playing { get; set; }Property Value
Scope
The asset scope behind this cache scope: typed handles (Load``1) with the same holds and lifetimes.
public AssetScope Scope { get; }Property Value
SlowLoadMilliseconds
A load during play that takes at least this many milliseconds is reported once on the error output, naming the file (4 by default: a quarter of a 60 Hz frame). Zero or less turns the reports off.
public double SlowLoadMilliseconds { get; set; }Property Value
Source
Where content files are read from (opened on first use): a folder, a zip archive or another source of the composition.
public IContentSource Source { get; }Property Value
Exceptions
The content folder does not exist.
Statistics
Counts, memory and load time of this scope and its children.
public AssetStatistics Statistics { get; }Property Value
Store
The game’s asset store: its content source, loaders and root scope.
public AssetStore Store { get; }Property Value
Methods
Atlas(string, AtlasOptions?, TextureFilter?)
The atlas a packing tool described at path (TexturePacker or Aseprite JSON, Starling XML) with the
image it names next to it.
public SpriteAtlas Atlas(string path, AtlasOptions? options = null, TextureFilter? filter = null)Parameters
path string
The atlas file.
options AtlasOptions?
Default pivot and naming; null for Default.
filter TextureFilter?
The texture’s filter; null for the game’s default.
Returns
Exceptions
The file or its image is missing or invalid.
AtlasFromFolder(string, Vector2, TextureFilter?)
Every image directly inside folder packed into one atlas at load, named by file name without its
extension (“items/gem.png” is “gem”): a folder of loose sprites, no packing tool needed.
public SpriteAtlas AtlasFromFolder(string folder, Vector2 pivot = default, TextureFilter? filter = null)Parameters
folder string
A folder of the content.
pivot Vector2
The anchor of every sprite as a fraction of its size; (0, 0), the top-left, by default.
filter TextureFilter?
The texture’s filter; null for the game’s default.
Returns
Exceptions
The folder is missing or holds no image, or an image cannot be read.
Bytes(string)
The bytes of any content file (not cached).
public byte[] Bytes(string path)Parameters
path string
Returns
byte[]
Exceptions
The file is missing or wrongly cased.
CreateScope(string?)
A child scope: an asset it asks for that another scope already loaded is the same object, and disposing the scope releases what it holds, disposing only what no other scope holds. Use one per level or scene whose assets should be freed when it ends.
public AssetCache CreateScope(string? name = null)Parameters
name string?
Returns
Dispose()
Releases every asset this scope and its child scopes hold, disposing those no other scope holds. The root scope is
disposed by the engine after Game.Unload.
public void Dispose()Font(string, FontOptions?)
The TTF or OTF font at path, drawn at any size (ScalableFont).
public ScalableFont Font(string path, FontOptions? options = null)Parameters
path string
options FontOptions?
Returns
Exceptions
The file is missing, wrongly cased or not a font the engine reads.
Image(string)
The image at path decoded into a new PixelImage each call (not cached: the game may
change it, for example to recolour it before packing).
public PixelImage Image(string path)Parameters
path string
Returns
Exceptions
The file is missing, wrongly cased or not an image the engine reads.
IsLoaded(string)
Whether this scope or one of its parents has path loaded (in any form).
public bool IsLoaded(string path)Parameters
path string
Returns
Music(string)
The music file at path (OGG, WAV; MP3 on raylib), read whole and decoded while it plays; play
it with Audio.AddMusic(name, music).
public EncodedAudio Music(string path)Parameters
path string
Returns
Exceptions
The file is missing or wrongly cased.
Preload(params string[])
Starts loading paths without blocking: images become textures, “.json” and “.xml” files atlases,
“.ttf” and “.otf” files fonts. Files are read and decoded on worker threads (see BackgroundDecoding);
the engine uploads finished ones each frame within FrameBudgetMilliseconds. Afterwards the usual
calls (Texture, Atlas, Font) return them at once.
public AssetBatch Preload(params string[] paths)Parameters
paths string[]
Returns
The batch, to show progress on a loading screen or wait for.
Sound(string)
The PCM WAV file at path decoded into a clip, shared and released like any asset; play it with Audio.AddSound(name, clip).
public AudioClip Sound(string path)Parameters
path string
Returns
Exceptions
The file is missing, wrongly cased or not an 8, 16 or 24-bit PCM WAV.
Text(string)
The text of any content file, as UTF-8 (not cached).
public string Text(string path)Parameters
path string
Returns
Exceptions
The file is missing or wrongly cased.
Texture(string, TextureFilter?)
The image at path as a texture, sampled with filter (the game’s default when null).
public Texture Texture(string path, TextureFilter? filter = null)Parameters
path string
filter TextureFilter?
Returns
Exceptions
The file is missing, wrongly cased or not an image the engine reads.
Unload(string)
Releases what this scope holds from path (in any form): each object is disposed unless another
scope still holds it, and loads again if asked for later. What only other scopes hold is not touched.
public bool Unload(string path)Parameters
path string
Returns
Whether this scope held anything from the file.
Update()
Finishes preloaded assets within FrameBudgetMilliseconds (at least one per call). The engine calls it
once per frame for Game.Assets; it also runs child scopes.
public void Update()