Preloading & Caching¶

Balancy stores images, views, fonts, and other files on a CDN. When your game needs an asset, the SDK downloads it and caches it locally so subsequent loads are instant. This page covers the client-side API for controlling this process — checking cache status, preloading assets on demand, and tracking download progress.

For server-side scheduling (automatic pre-loading based on conditions), see Assets Scheduling.

UnnyObject¶

Every CDN asset in Balancy is represented by an UnnyObject. The code generator automatically creates UnnyObject fields when you add Image, View, or Other File parameters to a template. An UnnyObject has a type (Sprite, View, or Asset) and a unique ID.

Check if Cached¶

Use IsCached() to check whether the file is already on disk — no download needed.

C#TypeScript

UnnyObject icon = myItem.Icon;

if (icon.IsCached())
    Debug.Log("Already on disk, LoadSprite will be instant");
else
    Debug.Log("Will need to download from CDN");

import { DataObjectsManager } from '@balancy/core';

if (DataObjectsManager.isCached(spriteId))
    console.log("Already on disk");
else
    console.log("Will need to download from CDN");

This is a synchronous call — it returns immediately without triggering any downloads.

Preload¶

Preload() downloads the asset to disk so it's available instantly when needed later. An optional callback reports success or failure.

C#TypeScript

// Preload without callback
myItem.Icon.Preload();

// Preload with callback
myItem.Icon.Preload(success =>
{
    Debug.Log(success ? "Preloaded!" : "Failed to preload");
});

import { DataObjectsManager } from '@balancy/core';

// Preload a sprite
DataObjectsManager.loadSprite(spriteId, blobUrl => {
    console.log(blobUrl ? "Preloaded!" : "Failed to preload");
});

// Preload a view
DataObjectsManager.getObjectView(viewId, (htmlCode, manifestPath) => {
    console.log(htmlCode ? "View preloaded" : "Failed");
});

Preload works for all object types:

Type	What happens
Sprite	Downloads the image file to disk. A `Texture2D` and `Sprite` are created and cached in memory.
View	Downloads the full view bundle — HTML, sprites, fonts, prefabs, scripts — via the manifest dependency chain.
Asset	Triggers Addressables loading (Unity only).

Deduplication

If the same asset is preloaded multiple times simultaneously (e.g. from user code and from a View dependency), the SDK deduplicates the requests — only one download happens, and all callers receive the result.

Load Sprite¶

To load a sprite for display:

C#TypeScript

myItem.Icon.LoadSprite(sprite =>
{
    if (sprite != null)
        myImage.sprite = sprite;
});

DataObjectsManager.loadSprite(spriteId, blobUrl => {
    if (blobUrl)
        imgElement.src = blobUrl;
});

If the file is already cached, the sprite is created immediately from the local file. Otherwise, the SDK downloads it first.

Open View¶

To load and display a view:

C#TypeScript

myItem.ViewObject.OpenView(() =>
{
    Debug.Log("View is shown");
}, ownerObject);

DataObjectsManager.getObjectView(viewId, (htmlCode, manifestPath) => {
    // htmlCode contains the HTML source
    // manifestPath points to manifest.json for the view
});

Clear from Memory and Disk¶

C#

// Remove sprite from memory (texture is destroyed)
myItem.Icon.ClearFromMemory();

// Remove from disk cache as well
myItem.Icon.ClearFromDisk();

Global Preload Status¶

When the SDK initializes, it downloads updated configs and scheduled assets. User-triggered Preload() calls add to this queue. You can track whether any downloads are still in progress globally.

IsPreloadingInProgress¶

Returns true if any data object downloads are currently active — including both init-time downloads and user-triggered preloads.

C#TypeScript

if (Balancy.Dictionaries.DataObjectsManager.IsPreloadingInProgress())
    Debug.Log("Downloads in progress...");
else
    Debug.Log("All downloads complete");

import { DataObjectsManager } from '@balancy/core';

if (DataObjectsManager.isPreloadingInProgress())
    console.log("Downloads in progress...");
else
    console.log("All downloads complete");

WaitForPreloading¶

Subscribe to a one-shot callback that fires when all pending downloads complete. If nothing is downloading, the callback fires immediately.

C#TypeScript

Balancy.Dictionaries.DataObjectsManager.WaitForPreloading(() =>
{
    Debug.Log("All assets are ready!");
    // Safe to show UI that depends on preloaded assets
});

import { DataObjectsManager } from '@balancy/core';

DataObjectsManager.waitForPreloading(() => {
    console.log("All assets are ready!");
});

Loading Screens

Combine IsPreloadingInProgress() and WaitForPreloading() to build loading screens:

// Show loading screen
loadingScreen.SetActive(true);

Balancy.Dictionaries.DataObjectsManager.WaitForPreloading(() =>
{
    loadingScreen.SetActive(false);
    ShowMainMenu();
});

Typical Workflow¶

A common pattern for assets that must be available before showing UI:

C#TypeScript

// 1. Preload all offer icons
foreach (var offer in activeOffers)
{
    offer.GameOffer.Icon?.Preload();
}

// 2. Wait for everything to finish
Balancy.Dictionaries.DataObjectsManager.WaitForPreloading(() =>
{
    // 3. All icons are now cached — show the offers UI
    ShowOffersScreen(activeOffers);
});

// 1. Preload all offer icons
for (const offer of activeOffers) {
    const iconId = offer.gameOffer?.icon?.id;
    if (iconId) {
        DataObjectsManager.loadSprite(iconId, () => {});
    }
}

// 2. Wait for everything to finish
DataObjectsManager.waitForPreloading(() => {
    // 3. All icons are now cached — show the offers UI
    showOffersScreen(activeOffers);
});

Summary¶

Method	Description
`IsCached()`	Synchronous check if the file is on disk
`Preload(callback)`	Download the asset to disk, with optional completion callback
`LoadSprite(callback)`	Download (if needed) and create a sprite
`OpenView(onShown, owner)`	Download (if needed) and display a view
`ClearFromMemory()`	Destroy the in-memory sprite/texture
`ClearFromDisk()`	Remove the file from disk cache
`IsPreloadingInProgress()`	Check if any downloads are active (global)
`WaitForPreloading(callback)`	Get notified when all downloads finish (global)