Skip to content

Visual Templates

Overview

Balancy provides ready-to-use visual templates for common LiveOps scenarios. These templates combine prefabs and built-in scripts to create fully functional UI elements out of the box.

Available Templates:

  • Shop views with multiple display modes
  • Offer and group offer displays
  • Purchase buttons with all price types
  • Item displays with rewards
  • Store slots with different layouts

Shop Templates

Balancy_View_Shop

A complete shop view that displays multiple pages with products.

Features:

  • Multiple pages support
  • Two display modes: Scroll and Tabs
  • Automatic slot instantiation
  • Purchase flow integration
  • Responsive layout

Components Used:

  • Balancy_UI_LiveOps_Shop
  • Balancy_UI_LiveOps_ShopPage
  • Balancy_UI_LiveOps_ShopSlot
  • Balancy_UI_LiveOps_StoreItem
  • Balancy_UI_Common_BuyButton
  • Balancy_UI_Common_BuyPrice

Configuration: 

// Set in shop component
useScrollMode: true  // Scroll mode vs tabs mode
defaultPagePrefab: reference to page prefab
tabsContainer: reference to tabs container
tabPrefab: reference to tab button prefab

Usage:

  • Assign the shop data to window.balancyViewOwner
  • Template automatically initializes all pages and slots
  • Handles purchase callbacks and state updates

[Visual Example - Screenshot to be added]

Purchase Button Templates

Balancy_Prefab_BuyButton

Universal purchase button that handles all pricing types and states.

Features:

  • Hard currency (IAP) pricing
  • Soft currency pricing
  • Ads-based pricing ("Watch 2/3 ads")
  • Cooldown timers
  • Locked/unavailable states
  • Insufficient funds visual feedback

Components Used:

  • Balancy_UI_Common_BuyButton
  • Balancy_UI_Common_BuyPrice

Pricing Types:

Hard Currency:

  • Shows localized price from platform store
  • Example: "$4.99", "€3.99"

Soft Currency:

  • Shows cost amount with currency icon
  • Example: "100" + coin icon

Ads:

  • Shows ad watch progress
  • Example: "Watch Ad (2/3)"

[Visual Example - Screenshot to be added]

Item Display Templates

Balancy_Prefab_ItemWithAmount

Displays an item with icon, name, and quantity/duration.

Features:

  • Item icon display
  • Localized item name
  • Smart count formatting (currency, regular items, time)
  • Timer icon for time-limited items
  • Configurable formatting options

Components Used:

  • Balancy_UI_LiveOps_ItemWithAmount

Formatting Examples:

  • Currency: "100" (plain number)
  • Regular items: "x50" (with prefix)
  • Time-based: "5h 32m" (localized compact)

[Visual Example - Screenshot to be added]

Store Slot Templates

Balancy provides multiple slot layouts for different visual styles.

Balancy_Prefab_SlotResources

Vertical layout emphasizing the main resource reward.

Layout:

  • Large main item display at top
  • Smaller additional rewards below
  • Buy button at bottom
  • Optimized for resource bundles

[Visual Example - Screenshot to be added]

Balancy_Prefab_SlotBundle

Horizontal layout for bundle offers.

Layout:

  • Rewards displayed in grid
  • Large icon on left
  • Buy button on right
  • Good for multi-item bundles

[Visual Example - Screenshot to be added]

Balancy_Prefab_SlotSmall

Compact layout for smaller card displays.

Layout:

  • Minimal footprint
  • Icon and price only
  • Best for grid displays with many items

[Visual Example - Screenshot to be added]

Offer Templates

Balancy_View_Offer

Displays a single offer with full details.

Features:

  • Large promotional image
  • Offer title and description
  • Countdown timer
  • Rewards display (main item + additional)
  • Purchase button
  • Auto-closes when expired

Components Used:

  • Balancy_UI_LiveOps_GameOffer
  • Balancy_UI_Common_BuyButton
  • Balancy_UI_Common_BuyPrice
  • Balancy_UI_LiveOps_ItemWithAmount (for rewards)

Timer Behavior:

  • Updates every second
  • Shows time remaining in human-readable format
  • Automatically closes view when timer expires
  • Calls balancy.closeView('Offer expired')

[Visual Example - Screenshot to be added]

Balancy_View_GroupOffer

Displays a group offer with multiple purchase options (chain deals).

Features:

  • Multiple offer slots
  • Sequential unlocking
  • Progress tracking
  • Individual timers per slot
  • Visual locked/available states

Components Used:

  • Balancy_UI_LiveOps_GameOfferGroup
  • Balancy_UI_Common_BuyButton
  • Balancy_UI_Common_BuyPrice
  • Balancy_UI_LiveOps_ItemWithAmount

Chain Deal Behavior:

  • Slot 1 available immediately
  • Slot 2 unlocks after purchasing Slot 1
  • Slot 3 unlocks after purchasing Slot 2
  • Visual feedback shows locked/available state

[Visual Example - Screenshot to be added]

Customizing Templates

All templates can be customized in the UI Builder:

1. Visual Customization

  • Modify colors, fonts, and sizes in Style tab
  • Replace images and icons
  • Adjust layout spacing and alignment
  • Add/remove visual elements

2. Script Parameter Customization

  • Configure formatting options
  • Set element references
  • Adjust timers and intervals
  • Change display modes

Example: 

// In ItemWithAmount component
timeFormat: 2           // Change to 0 for full date format
currencyFormat: 4       // Change to 0 for plain numbers
regularItemFormat: 2    // Change to 0 to remove "x" prefix

3. Prefab Customization

  • Create variants of templates
  • Add custom scripts
  • Combine multiple templates
  • Build composite layouts

Example: Custom Shop Slot 

<!-- Start with Balancy_Prefab_SlotResources -->
<!-- Add custom badge -->
<div data-script-id="CustomBadge"></div>

<!-- Add custom animation -->
<div data-script-id="PulseAnimation"></div>

Template Best Practices

1. Use Prefab Variants

Don't modify built-in templates directly. Create variants:

  1. Duplicate the template in UI Builder
  2. Rename (e.g., "Balancy_Prefab_BuyButton_Custom")
  3. Make your modifications
  4. Use the custom version in your views

2. Maintain Component Structure

Templates rely on specific component hierarchies. When customizing:

  • Keep required script components
  • Maintain element references
  • Preserve serialized parameters
  • Don't remove essential child elements

3. Test All States

When customizing button/slot templates, test:

  • Available state
  • Unavailable state (insufficient resources)
  • Cooldown state (with timer)
  • Locked state
  • All price types (Hard, Soft, Ads)

4. Responsive Design

Templates are designed for multiple screen sizes:

  • Use percentage-based widths
  • Test in different aspect ratios
  • Use UI Builder's device selector
  • Check both portrait and landscape

Integration Examples

Shop Integration

// Main shop view script
class ShopView extends balancy.ElementBehaviour {
    // @serialize {element}
    shopComponent = null;

    async awake() {
        const shopData = window.balancyViewOwner;
        const script = this.shopComponent.getComponent(Balancy_UI_LiveOps_Shop);
        script.init(shopData);
    }
}

Offer Integration

// Offer view script
async function main() {
    const offerInfo = window.balancyViewOwner;

    const viewObject = await balancy.instantiatePrefabById('offer-view');
    const script = viewObject.getComponent(Balancy_UI_LiveOps_GameOffer);
    script.init(offerInfo);

    document.body.appendChild(viewObject.element);
}

window.addEventListener('balancy-ready', main, { once: true });

Custom Buy Button

// Using buy button in custom context
class CustomOffer extends balancy.ElementBehaviour {
    // @serialize {element}
    buyButton = null;

    async start() {
        const button = this.buyButton.getComponent(Balancy_UI_Common_BuyButton);

        await button.init({
            price: this.myOffer.price,
            storeItem: this.myOffer.storeItem,
            state: balancy.BuyButtonState.Available,
            onBuy: () => this.handlePurchase()
        });
    }

    async handlePurchase() {
        const result = await balancy.buyOffer();

        if (result.success) {
            // Update button to cooldown
            const button = this.buyButton.getComponent(Balancy_UI_Common_BuyButton);
            button.setState(balancy.BuyButtonState.Cooldown, {
                cooldownSeconds: result.cooldownTime
            });

            // Show success message
            this.showSuccessMessage();
        }
    }
}

Troubleshooting

Template Not Displaying

Problem: Template prefab loads but nothing shows.

Solutions:

  • Check that data-prefab-id is correct
  • Verify prefab is cached and loaded
  • Look for JavaScript errors in console
  • Ensure init() was called on script components

Buttons Not Working

Problem: Buy button doesn't respond to clicks.

Solutions:

  • Verify buttonElement reference is set
  • Check onBuy callback is provided
  • Ensure button state is Available
  • Check for pointer-events: none CSS

Images Not Loading

Problem: Item icons or sprites not showing.

Solutions:

  • Verify image IDs are correct
  • Check that balancy.setImage() was called
  • Look for 404 errors in Network tab
  • Ensure images were uploaded to Balancy

Timer Not Updating

Problem: Countdown timer frozen.

Solutions:

  • Verify update() is being called
  • Check component is enabled
  • Ensure element is active in hierarchy
  • Look for errors in _updateTimer() method

Next Steps

Note: Visual examples with screenshots will be added in this section. Each template will include: - Screenshot showing the template in action - Layout diagram highlighting key areas - Configuration options table - Usage code examples