CacheManager class
Manages caching of various game resources.
Strings and JSON go to the engine's own key-value store, binary data to
the engine's own database. On desktop and mobile the key-value store is
a file of its own, just_game_engine/just_storage.json in the app's
support directory — not the just_storage.json app code opens with
JustStorage.standard, because just_storage rewrites a whole file from
the copy each instance loaded, and two instances on one file drop each
other's keys. On the web it is browser storage under the engine's own key
prefix. Everything the cache writes sits under keyPrefix, so clearAll
removes only the cache's own entries — never the engine settings kept
beside them (such as players' key bindings).
Before 2.0 the engine wrote into the app's just_storage.json. The first
run moves what it left there — its prefixed entries, and players'
bindings saved before 2.0 — into its own store, and removes them and any
pre-2.0 copies of bundle assets from the app's file. Nothing else there
is touched.
When a store cannot be opened or stops accepting writes, the entries it should have held are kept in memory for the rest of the run instead.
Assets from the app's bundle are not cached here: the bundle is already on the device, and a copy kept across runs outlived the asset it was made from — an update shipping a new image went on drawing the old one.
The binary cache supports optional eviction via maxBinaryEntries. When the limit is reached, the oldest entries (by write time) are removed to make room for new ones.
Constructors
-
CacheManager({int? maxBinaryEntries, bool forceMemoryFallback = false, Future<
JustStandardStorage> openStorage()?, Future<JustDatabase> openDatabase()?, }) - Create a cache manager.
Properties
- forceMemoryFallback → bool
-
Forces the cache to use only the shared in-memory fast path.
final
- hashCode → int
-
The hash code for this object.
no setterinherited
- isBinaryInMemory → bool
-
Whether binary data is kept in memory only — the database could not be
opened or set up — while strings may still reach the key-value store.
no setter
- isInitialized → bool
-
Check if cache manager is initialized
no setter
- isUsingMemoryFallback → bool
-
Whether the cache is running in headless/test memory-only mode.
no setter
- maxBinaryEntries → int?
-
Maximum number of entries in the binary cache before eviction.
nullmeans effectively unbounded in in-memory fallback mode.final - runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
captureProfile(
) → MemoryProfileSnapshot - Returns a lightweight profiling snapshot for runtime tuning.
-
clearAll(
) → Future< void> - Clear all cache entries.
-
dispose(
) → void - Dispose of the cache manager and close resources
-
getBinary(
String key) → Future< Uint8List?> - Retrieve binary data
-
getBinaryCacheSize(
) → Future< int> - Return the number of entries in the binary cache.
-
getJson(
String key) → Future - Retrieve JSON data
-
getString(
String key) → Future< String?> - Retrieve a string value
-
initialize(
) → Future< void> - Initialize the caching system. Calls made while one is under way wait for it; a dispose meanwhile closes what it opened.
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
remove(
String key) → Future< void> - Clear a specific cache entry (from both storages for simplicity)
-
setBinary(
String key, Uint8List data) → Future< void> - Store binary data.
-
setJson(
String key, dynamic data) → Future< void> - Store JSON data
-
setString(
String key, String value) → Future< void> - Store a string value
-
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited