HyperCasual
Essentials

🏠 Overview

Everything you need for a hyper-casual game, nothing you don't.

⚡ Quick Start

Get up and running in under 2 minutes.

Automatic Bootstrap

At runtime, two bootstrappers fire automatically — no scene setup required:

GameBootstrapper applies your HCESettings: target frame rate (default 60), screen sleep prevention, time scale restoration, and multi-touch.

Sample Prefabs

🛠 Architecture

How everything connects under the hood.

Service Locator Pattern

All modules register and resolve dependencies through the static HCE.Core.Services class. This keeps systems decoupled — Audio doesn't know about Economy, Economy doesn't know about Shop.

Factory Pattern

Platform-specific backends (Ads, Haptics, IAP, Notifications, Rate Us) are created by factory classes that read HCESettings and select the right implementation. Missing SDKs gracefully fall back to dummy/mock backends.

ScriptableObject Configuration

Every system is configured through Inspector-editable ScriptableObject assets. No hardcoded values, no code changes needed for designers to tune behavior.

Event-Driven Updates

Services emit C# events (BalanceChanged, Purchased, SpinCompleted, etc.) so UI automatically reacts to state changes without polling.

Folder Structure

HyperCasualEssentials/
  Config/            // Default ScriptableObject configs
  Demo/              // Feature dashboard
  Documentation~/    // This documentation
  Editor/            // Editor windows, inspectors, importers
  Plugins/           // Native iOS/Android code
  Resources/HCE/     // HCESettings singleton + icons
  Runtime/           // All game systems (148 C# files)
    Ads/  Analytics/  Audio/  Cheats/  Core/
    DailyReward/  Economy/  Flow/  Gating/
    Haptics/  IAP/  Minigames/  Notifications/
    RateUs/  Save/  Shaders/  Shop/  UI/  Wheel/
  Samples~/          // Optional importable demo

🔌 Service Locator

Minimal static registry for dependency injection.

// Register a service (once, during bootstrap)
Services.Register<AudioService>(new AudioService());

// Resolve anywhere
var audio = Services.Resolve<IAudioService>();
audio.Play(new SoundId("click"));

// Safe resolve (no exception if missing)
if (Services.TryResolve<IWalletService>(out var wallet))
    wallet.Credit(CurrencyId.Coins, 100, "bonus");C#

⚙ HCE Settings

Single ScriptableObject configuring every module.

Located at Resources/HCE/HCESettings.asset. Access at runtime via HCESettings.Instance. Falls back to safe defaults if the asset is missing.

💾 Save System

Versioned JSON blobs with schema migration and debounced writes.

How It Works

All game state is serialized into a SaveBlobV1 and stored in a single PlayerPrefs key (HCE_SAVE_V1). Writes are debounced to at most once per second to avoid I/O spam.

// Save
var blob = new SaveBlobV1();
walletService.SaveToBlob(blob);
shopService.SaveToBlob(blob);
backend.WriteBlob(blob);

// Load
var loaded = backend.ReadBlob();
if (loaded != null) {
    loaded = SaveMigrator.Upgrade(loaded, loaded.SchemaVersion, SaveMigrator.CurrentVersion);
    walletService.LoadFromBlob(loaded);
    shopService.LoadFromBlob(loaded);
}C#

SaveBlobV1 Structure

Schema Migration

When adding new fields, create a new schema version and register an upgrader in SaveMigrator.Upgrade(). The migrator chains upgrades: V0 → V1 → V2 → etc.

🎬 Scene Flow

Async scene loading with fade transitions and cooldown timers.

SceneFadeService

Load scenes with a smooth fade-out / load / fade-in sequence. Uses unscaled delta time so it works even when the game is paused.

var fadeService = new SceneFadeService(fadeConfig, overlayImage);
await fadeService.LoadAsync(sceneRef);C#

CooldownTimer

Invariant-culture cooldown gate. Serializes to tick strings that are safe across locales and devices.

var timer = new CooldownTimer(timeSource, TimeSpan.FromHours(24), "daily_reward", savedStamp);
if (timer.IsReady) {
    // Grant reward
    timer.Stamp();
    PlayerPrefs.SetString("stamp", timer.ToSave());
} else {
    Debug.Log($"Ready in {timer.Remaining.TotalHours:F1}h");
}C#

Time Sources

Tweening

Lightweight static tween driver via TweenRunner. Supports Move, Rotate, Scale, and Fade with easing and cancellation.

TweenRunner.Scale(transform, Vector3.zero, Vector3.one, 0.4f, Easing.OutBack);
TweenRunner.Fade(canvasGroup, 0f, 1f, 0.3f, Easing.InOutSine);C#

Available easing functions: Linear, InOutQuart, InOutSine, OutCubic, OutBack.

🔊 Audio

Pooled SFX playback, crossfading music, and a per-category mixer.

Setup

// Play SFX
var audio = Services.Resolve<IAudioService>();
audio.Play(new SoundId("click"));
audio.Play(new SoundId("explosion"), 0.5f);  // 50% volume

// Play music with crossfade
audio.PlayMusic(new SoundId("menu_loop"), 2f);

// Mixer control
audio.SetVolume(AudioCategory.Sfx, 0.8f);
audio.SetMute(AudioCategory.Music, true);C#

SoundBank Entry Fields

CSV Import

Bulk-populate a SoundBank: select it in the Project window, then Tools → HCE → Import SoundBank CSV.

# id, clipName, volume, pitch, pitchJitter
click, UI_Click, 0.8, 1.0, 0.05
footstep, Footstep_Concrete, 1.0, 1.2, 0.1
ambient_wind, , 1.0, 1.0, 0CSV

Audio Mix Formula

Final Volume = Entry.Volume × Master × Category
               (0 if MasterMuted OR CategoryMuted)
Final Pitch  = Entry.Pitch ± Random(PitchJitter)text

📳 Haptics

Pattern-based vibration with platform-specific backends.

Setup

var haptics = new HapticService();
haptics.Initialize();

var pattern = Resources.Load<HapticPattern>("Light");
haptics.Play(pattern);
haptics.Cancel();  // Stop vibrationC#

HapticPattern Fields

Platform Backends

Mode Configuration

In HCESettings → Haptics:

• Disabled: All calls dropped silently
• Dummy: Logs to console, no vibration
• Production: Real platform vibration

💰 Economy

Multi-currency wallet with overflow protection and transaction logging.

Wallet Service

// Credit
wallet.Credit(CurrencyId.Coins, 500, "level_complete");

// Debit (returns false if insufficient)
if (wallet.TryDebit(CurrencyId.Gems, 10, "shop_purchase")) {
    // Purchase succeeded
}

// Read balance
long coins = wallet.Get(CurrencyId.Coins);

// Listen for changes
wallet.BalanceChanged += (id, newBalance) => UpdateHud(id, newBalance);C#

Built-in Currencies

CurrencyId.Coins and CurrencyId.Gems are predefined. Create custom currencies with new CurrencyId("keys").

Overflow Protection

Balances are capped at long.MaxValue / 2 instead of crashing on overflow. Safe for long-term play sessions.

Transaction Log

Every credit/debit is recorded in a ring buffer (default 50 entries) with timestamp, currency, delta, and reason string. Use transactionLog.GetRecent(10) for analytics or debugging.

Coin Burst Animation

Spawn a stream of coins flying from a world position to your HUD:

var request = new CoinBurstRequest {
    CoinCount = 15,
    TotalReward = 100,
    OriginWorld = transform.position,
    HudPositionProvider = () => hudCoinIcon.position,
    StaggerSeconds = 0.02f
};
coinBurstRunner.PlayAsync(request, onCompleted: () => Debug.Log("done"));C#

🛒 Shop & Skins

Item catalog with material and mesh skin payloads.

Setup

// Purchase
if (shopService.TryPurchase(item)) {
    Debug.Log("Bought!");
}

// Equip
shopService.Equip(item);  // Fires Equipped event → SkinApplier applies it

// Events
shopService.Purchased += (item) => ShowToast("Purchased!");
shopService.Equipped += (item) => RefreshUI();C#

CSV Import

Select a ShopCatalog, then Tools → HCE → Import Shop CSV:

# id, price, currency, englishName
blue_skin, 100, coins, Blue Skin
fire_sword, 50, gems, Fire SwordCSV

Skin Payload Types

💳 In-App Purchases

Unified purchase flow with real and dummy store backends.

Product Setup

Purchase Flow

var result = await iapBridge.PurchaseAsync("com.game.1000coins");
if (result.Success) {
    // Reward already granted via RewardHook
    ShowToast("Thank you!");
}C#

Reward Hook Types

Failure Reasons (PurchaseResult.Reason)

The Unity IAP backend pre-validates every purchase request before calling the store, so failures surface as a clean PurchaseResult { Success = false, Reason = "..." } instead of throwing. Show Reason in toasts/logs to diagnose live issues.

Dummy Backend

The dummy backend simulates purchases with configurable behavior:

• AlwaysSucceed: Returns success with dummy receipt
• AlwaysFail: Returns "simulated_failure"
• AlwaysCancel: Returns "user_cancelled"

Latency is configurable (default 250ms) to test loading spinners.

📺 Ads

AdMob integration with rewarded, interstitial, and banner support.

Showing Ads

var adService = Services.Resolve<AdService>();

// Rewarded video
var result = await adService.ShowRewardedAsync(rewardedPlacement);
if (result.Completed) GrantReward();

// Interstitial
bool shown = await adService.ShowInterstitialAsync(interstitialPlacement);

// Banner
adService.LoadBanner(bannerPlacement);
adService.HideBanner(bannerPlacement);C#

RewardedResult

Mode Configuration

Production Setup

🎁 Daily Rewards

Streak-based welcome gifts with ad-boosted claiming.

How It Works

Streak Logic

• Same day: No-op (already claimed)
• Next day: Streak increments
• Skipped days: Streak resets to 1 (unless grace days configured)

Default Schedule

Ad-Boosted Claiming

// 2x reward via rewarded ad
if (service.TryClaimWithMultiplier(2, out var gift)) {
    ShowCelebration(gift);
}C#

The WelcomeGiftPanel UI has built-in "x2 via Ad" button support. Wire an AdPlacement in settings and the panel handles the ad flow automatically.

Welcome Gift Configuration

Tile States

The WelcomeGiftPanel renders each day as a tile with one of four states:

• Claimed: Dimmed (already collected)
• Today: Highlighted green (claimable now)
• Locked: Dark overlay (future day)
• Missed: Faded (grace days feature)

🎱 Reward Wheel

Weighted prize spinner with visual building and tick audio cues.

Setup

wheelSpinner.Spin();
wheelSpinner.SpinCompleted += (result) => {
    Debug.Log($"Won {result.Slice.Amount} coins!");
    wallet.Credit(CurrencyId.Coins, result.Slice.Amount, "wheel_reward");
};C#

WheelSlice Fields

Spin Animation

The spinner performs _extraSpins full rotations (default 5) before landing on the selected slice, using InOutQuart easing over _spinDuration seconds (default 4s).

The WheelTickEmitter fires a Tick event for every slice boundary crossed — perfect for driving a click sound.

Weighted Selection

Uses prefix-sum binary search for O(log N) selection. Zero-weight slices are never selected. The inspector warns if total weight is 0 or slice count is outside 2–12.

🎲 Minigames

Chest loot drops and slot machine.

Chests

var result = chestService.TryOpen("rare_chest");
if (result.Success)
    Debug.Log($"Got {result.Drop.Amount} {result.Drop.CurrencyId}!");C#

Each ChestTier has a key cost (debited from wallet), an icon, a tint color, and a weighted loot table of ChestRewardDrop entries. Drops can grant currency or set item flags.

Slot Machine

if (slotMachine.TrySpin(out var result)) {
    if (result.HitJackpot)
        Debug.Log($"JACKPOT! Won {result.RewardAmount}!");
}C#

Configure reels, symbols (with weights), and payout rules. The default setup: 3 reels, symbols Cherry/Lemon/Bell/Bar/Seven with payouts from 30 to 2500.

🔒 Feature Gating

Lock features behind level, currency, cooldown, or flag conditions.

UnlockGate Component

Add an UnlockGate to any Button. Assign an UnlockCondition asset. The gate automatically disables the button, shows a lock reason, and toggles a lock overlay.

Condition Types

Usage

// Listen for gate status changes
unlockGate.StatusChanged += (status) => {
    if (status.Unlocked)
        Debug.Log("Feature unlocked!");
    else
        Debug.Log(status.LockReason);
};C#

🗨 Popups & Toasts

Modal popup stack and FIFO toast notifications.

Popups

// Show a popup
popupService.Open(new PopupRequest(myPopupPrefab, dimBackdrop: true, payload: someData));

// Close from inside the popup
public class MyPopup : PopupView {
    public override void OnOpened(object payload) { /* setup UI */ }
    public void OnCloseClicked() => Close();
}C#

Popups stack. The backdrop uses reference counting — it stays visible until all popups are closed. Set IgnoreTimeScale = true for pause-proof animations.

Toasts

toastService.Show(new ToastRequest("Level complete!", ToastKind.Success, 2f));
toastService.Show(new ToastRequest("Not enough coins", ToastKind.Warning));C#

Toast Kinds

Toasts queue in FIFO order with 0.1s pause between each. Duration defaults to 2 seconds.

🎨 UI Helpers

Ready-made components for common UI patterns.

// NumberTicker usage
numberTicker.SetImmediate(0);
numberTicker.TweenTo(1500);  // Animates 0 → 1500 over 0.6sC#

🌈 Toon Shaders

Cel-shaded rendering for BiRP, URP, and HDRP.

Shader Variants

Material Properties

Pipeline Detection

// Auto-select the right shader for the active pipeline
string shaderName = RenderPipelineUtil.GetPreferredToonShader();
var shader = Shader.Find(shaderName);C#

📊 Analytics

Pluggable event bus with multiple sink backends.

var bus = Services.Resolve<AnalyticsBus>();
bus.Emit("level_complete", new Dictionary<string, object> {
    { "level", 5 },
    { "score", 1200 },
    { "time_seconds", 42.5 }
});C#

Available Sinks

Sinks are isolated — if one throws, others still receive the event. Configure in HCESettings → Analytics.

🔔 Notifications

Schedule local push notifications on mobile.

var svc = NotificationService.CreateFromSettings();
await svc.InitializeAsync();
await svc.RequestPermissionAsync();

// Schedule a notification 4 hours from now
string id = svc.Schedule("Come back!", "Your energy is full.", TimeSpan.FromHours(4));

// Cancel it
svc.Cancel(id);
svc.CancelAll();C#

Platform Behavior

⭐ Rate Us

Gated review prompts with platform-native dialogs.

// Register each app launch
rateUsService.RegisterSession();

// Gated prompt (checks all conditions first)
var result = await rateUsService.MaybeRequestReviewAsync();

// Force prompt (for explicit "Rate Us" button in settings)
var result = await rateUsService.ForceRequestReviewAsync();C#

Gate Conditions

Soft Prompt

Enable UseSoftPrompt to show a custom dialog ("Enjoying the game?") before the native review UI. If the user declines, the attempt is counted but the native dialog is skipped.

Production Setup — Native Popup Wiring

HCE ships a fully self-contained wiring for the Android native popup — no project-level Gradle edits required. iOS needs nothing at all.

🔧 Editor Tools

Setup wizard, toolset window, custom inspectors, and CSV importers.

Tools Menu

Toolset Window

The main HCE editor window (11 tabs) shows the health status of every module:

• ● Green: Module ready
• ● Yellow: Warning (e.g., SDK missing but not required)
• ● Red: Action needed (e.g., production IDs missing)

Tabs: Overview, Ads, Analytics, IAP, Audio, Haptics, Notifications, Rate Us, Welcome Gifts, Minigames, General.

Custom Inspectors

Property Drawers

Smart dropdown pickers are provided for SoundId, CurrencyId, ShopItemId, and SceneReference fields. They auto-scan all relevant assets in the project.

Build Validator

Runs automatically before every build (IPreprocessBuildWithReport). Warns if a SoundBank or ShopCatalog is missing — never blocks the build.

🎮 Cheat Console

Debug console with hotkeys and 3-finger mobile gesture.

Activation

• Keyboard: Press ` (backtick) to toggle the console
• Mobile: 3-finger long-press for 1+ second

Built-in Cheats

CheatBindings Config

Create via Create → HCE → Cheats → Bindings. Customize hotkeys and grant amounts in the Inspector.

📚 Scripting Defines

Feature flags for optional SDK integrations.

💡 Troubleshooting

Common issues and their solutions.

Threading Rules

📬 Support

Need help? We're here for you.