Game Setup Assistant

Tools > HLK > Game Setup Assistant is the recommended starting point for a new developer. It edits the real runtime assets directly; it is not a demo or a second configuration copy. Use it for game content and balancing. Use Advanced Toolset for SDK providers, store credentials, AdMob IDs, consent, platform defines, and production checks.

Recommended first setup

1. Open the assistant and click Apply Missing Presets. It fills empty references only and never replaces an assigned asset.
2. On Game & Levels, enter the menu and gameplay scene names and tune the initial level range. Click Add Both to Build Settings; the menu becomes build index 0.
3. Edit minigame, goal, daily-gift, shop, and battle-pass assets inline. Use the Ping button whenever you want the normal Inspector or want to duplicate an asset.
4. Open Validate and clear red items. Yellow items are recommendations or production integrations that may intentionally remain simulated during development.

Advanced module coverage

The Services page also shows the boundary between designer-safe fields and provider-heavy setup. Ads Pro, IAP Pro, app updates, attribution, crash reporting, deep links, permissions, push messaging, remote config, and web views remain in the Advanced Toolset. They are not omitted: the assistant links to their full configuration pages and its automated coverage test verifies that every public HLKSettings section belongs to exactly one of these two surfaces.

Useful editor and CI entry points

• Tools > HLK > Validate Game Setup opens the assistant directly on its validation report.
• Tools > HLK > Open Combined Documentation opens this file from Unity.
• Automated builds can run -executeMethod HLK.StarterMenu.Editor.HLKGameSetupValidator.ValidateForCi. The command logs every finding and fails the process only for blocking errors; recommendations remain warnings.

Starter Menu & Level Customization

The reusable portrait menu lives in StarterMenu/Scenes/HLK_MainMenu.unity. Its game destination is configured by name rather than a direct scene reference, which makes the package easy to move between projects.

Levels

• VisibleLevelCount controls the number of generated choices.
• AvailableLevelCount is the fresh-install unlock count. Save data then owns progression.
• The level panel's DEV menu switches between horizontal cards, a 3×3 grid, infinite vertical scroll, and the centered vertical-road selector. These are presentation layouts over the same level data.
• WinCoinReward feeds the animated win panel and wallet fly-out. Currency particles terminate on the matching coin or diamond icon.

Minigames

Cooldowns are authored in minutes and stored as UTC completion timestamps, so closing the app does not reset them. A value of 0 disables that minigame's cooldown. The Mystery Chest key count is clamped to the nine board cells.

Goals, achievements, and gameplay events

A QuestDefinition.Kind decides where the item appears: Permanent is an achievement; Daily, Weekly, and Event are goals. Its ID is the persistence key—keep it stable after release. Event names are exact, case-sensitive strings.

// Count one completion for definitions listening to "level_complete".
var props = new Dictionary<string, object> {
    { "level", currentLevel },
    { "stars", earnedStars }
};
AnalyticsBus.Emit("level_complete", props);

// To sum a value, choose EventPropertySum and set PropertyName to "amount".
AnalyticsBus.Emit("currency_earned",
    new Dictionary<string, object> { { "amount", 50 } });

The Achievements DEV panel is for QA progress/claim manipulation only. Do not use DEV actions as production progression logic.

Shop, cosmetics, and reusable unlock rules

The Economy & LiveOps page can create the default Resources-loaded ShopCatalog, add ShopItem assets, and edit both inline. Shop items support coin/gem prices, consumable or permanent ownership, IAP/rewarded-ad entitlement sources, prerequisite items, free-claim cooldowns, and swappable cosmetic effects.

The same page creates level, currency, cooldown, flag, and composite UnlockCondition assets. Assign a condition to an UnlockGate on the content being gated. Conditions only evaluate availability; explicitly consume/spend the requirement from game logic when that is part of your design.

Daily gifts

Index 0 in the schedule is Day 1. Each entry can grant coins, gems, or an item and can be marked special for highlighted presentation. GraceDays controls missed-day tolerance. LoopAfterLastDay repeats the last authored reward; disable it for a finite calendar. The optional HTTP time probe reads a trusted Date header to make simple device-clock cheating harder.

UI and art replacement

Currency, shop, minigame, leaderboard, chest, and battle-pass artwork is stored below StarterMenu/Art and StarterMenu/Resources/HLK/StarterMenuArt. Power-up artwork is intentionally kept with its portable module under PowerUps/Art. Preserve transparent padding when replacing icons, use Sprite (2D and UI), and keep background art on an aspect-cover component so portrait devices do not stretch it. Decorative images must have Raycast Target disabled.

Using the Backend in Another Game

The kit is intentionally portable. Export the following folder as the reusable backend and menu:

Assets/HyperCasualLiveOpsKit

Third-party SDK source and binaries belong outside that folder:

Assets/__DO_NOT_PUBLISH_VENDOR_SDKS

When importing into a new project:

1. Import the HLK folder and let Unity compile using simulated backends.
2. For a power-up-only integration, copy the complete PowerUps folder, open Tools > HLK > Power-Ups > Setup & Catalog, and provide a small IPowerUpEffectHandler adapter for each game-specific effect.
3. Open Game Setup Assistant, apply missing presets, and change both scene names.
4. Duplicate/tune the catalogs in GameSetup, then connect your gameplay events.
5. Only after the game-facing validation passes, import the vendor SDKs you need into the excluded folder and configure their matching Advanced Toolset tabs.
6. Use test ads and fake/sandbox purchases until store console products and privacy flows are ready.

Getting Started

Requirements: Unity 6000.0+, TextMeshPro (com.unity.textmeshpro) and uGUI (com.unity.ugui). UPM installs pull these in automatically; a raw .unitypackage import expects both packages to already be present in the project.

From import to a running showcase in about five minutes:

1. Import the package. Only the toolkit's own files are added — no registries, no manifest edits, no binaries. Everything compiles immediately because each module defaults to a self-contained in-engine backend.
2. Open the demo. Load Assets/HyperCasualLiveOpsKit/Demo/HLK_Showcase.unity and press Play. The dashboard exercises nearly every module live: earn coins, spin the wheel, trigger toasts, simulate purchases, and more. (Content Gating / Unlocks is setup-only — it has no demo panel.)
3. Open Game Setup Assistant. Go to Tools > HLK > Game Setup Assistant for levels, minigames, achievements, goals, daily gifts, shop data, battle pass, and validation. Open its Advanced Toolset only when configuring provider SDKs or platform services.
4. Generate starter data. Trigger Tools > HLK > Generate Starter Config Assets — it creates ready-made preset assets (IAP catalog, wheel slices, chest tiers, quest catalog, battle pass season, and the rest) under Assets/HyperCasualLiveOpsKit/Presets/, pre-wired into HLKSettings.
5. Go native when ready. Out of the box the modules run in their safe Dummy / Simulated / In-Engine modes so the project builds and plays with no SDKs. To get real native behaviour on device, switch each module's mode on its Toolset tab — see Real native features on device below for exactly what each one costs (several need only a mode change and no account at all).

Architecture Overview

The kit is organized as independent modules under Runtime/, each with the same internal shape. Understanding the shape once means you understand every module:

• Service — a plain C# class holding the logic (e.g. SaveService, AdService, QuestService). Testable without a scene.
• Interface — the seam consumers depend on where behavior can vary (e.g. IAudioService, IGameServices).
• Backend + factory — platform or vendor adapters behind the interface. A *BackendFactory picks one from the configured mode and the compiled defines; a dummy or simulated backend always exists, so nothing breaks without SDKs.
• Bootstrap — a static class with a RuntimeInitializeOnLoadMethod hook that builds the service from settings and registers it in the service registry.
• Settings section — a serializable block inside HLKSettings, drawn by the matching Toolset tab.

The persistent host

MonoHost is a hidden, scene-surviving MonoBehaviour created before the first scene loads. It runs coroutines for headless services (MonoHost.Run), exposes per-frame events, and — critically — provides MonoHost.Post(Action) so background SDK callbacks can hand work back to the main thread.

Threading rules

Results instead of exceptions

Fallible operations return HlkResult / HlkResult<T> — a success flag plus a structured HlkError — rather than throwing across module boundaries. Check result.Success, or use ValueOr(fallback) / TryGet(out value) on the generic form.

Service Registry

HLK.Core.Services is a minimal type-keyed locator. Modules register one shared instance per capability at bootstrap (usually keyed by interface); game code resolves it anywhere without wiring references through the scene.

Registration keys you can rely on after boot include SaveService, IFlowService, IAudioService, IHapticService, IWallet, IAPBridge, AdService, IShopService, IOffersService, StarterGiftService, WheelService, IQuestService, IBattlePassService, IEnergyService, IGameServices, CloudSaveService, IConsentService, IPushService, SharingService, WebViewService, IDeepLinkService, IRemoteConfig, IAppUpdateService, IAttributionService, CrashReporterService, INotificationService, IRateUsService, IPermissionsService, IPopupService, IToastService, ILocalizationService, IEntitlements, ITimeSource, and ICheatService.

Configuration Assets

All module configuration funnels into a single ScriptableObject, HLKSettings, which must live at Assets/HyperCasualLiveOpsKit/Resources/HLK/HLKSettings.asset to be found at runtime (Resources path HLK/HLKSettings). Access it in code through HLKSettings.Instance — if the asset is missing, a transient, fully-defaulted instance is served so nothing null-refs.

Sections

One serializable section per module: Ads, AdsPro, Analytics, AppUpdate, Attribution, Audio, BattlePass, CloudSave, Consent, CrashReporter, DeepLinks, Energy, GameServices, General, Haptics, IAP, IAPPro, Localization, Minigames, NativeUI, Notifications, Offers, Permissions, Push, Quests, RateUs, RemoteConfig, Sharing, WebView, and StarterGifts.

Preset assets

Data-heavy modules reference standalone ScriptableObjects. The generator at Tools > HLK > Generate Starter Config Assets creates a working set under Assets/HyperCasualLiveOpsKit/Presets/ and assigns each into the right settings slot:

Save System

A versioned, migration-aware persistence layer built around one consolidated record. Game state lives in a single SaveBlob (currency balances, owned items, streak data, string flags) that is serialized as JSON through a pluggable ISaveBackend — PlayerPrefsSaveBackend by default.

Schema versioning

The current schema version is SaveSchema.Current = 2. Older payloads pass through SaveMigrator, which chains ISaveMigration steps (Migration_V0_to_V1, Migration_V1_to_V2) until the record is current. Add your own step when you change the blob's shape.

Storage keys are namespaced under the HLK_ prefix — the blob itself sits at HLK_SAVE_V1 with a schema marker alongside it.

Scene Flow & Timing

Scene navigation with a built-in fade, plus the small timing primitives the rest of the kit leans on: serializable cooldowns, swappable clocks, and a lightweight tween helper.

Faded scene loads

SceneFadeService implements IFlowService, raises TransitionStarted / TransitionCompleted, and reports IsTransitioning while a fade-load-fade sequence runs. A SceneReference field gives designers a drag-and-drop scene picker that survives renames.

Cooldowns

Time sources

ITimeSource abstracts "what time is it" so reward logic can resist device-clock cheating. LocalTimeSource uses the device clock; ServerTimeSource anchors to a remote clock. TimeSourceFactory registers the configured one as the shared ITimeSource.

Tweens

TweenRunner (in HLK.Core) animates floats, vectors, transforms, and CanvasGroup alpha on the persistent host. The Easing library covers the standard curve families — Sine, Quad, Cubic, Quart, Quint, Expo, Circ, plus Back, Elastic, and Bounce — each with in / out / in-out variants selected via EaseType.

Audio Engine

Pooled one-shot SFX and crossfading music behind a tiny interface. Designers author a SoundBank asset — named entries with a clip, category, volume, pitch, and optional pitch jitter — and code addresses sounds by SoundId (implicitly convertible from string).

Portable game sound palette

The included AudioLibrary/Clips folder contains 45 clearly named WAV effects. Run Tools > HLK > Audio > Install Game Sound Library after importing or replacing clips. The installer builds HLKGameSoundBank, assigns it to settings, and configures a 32-voice pool so fast repeated sounds—including the same sound—can overlap.

Mixing model

The final gain of a voice is the product of three sliders: Master × Category × entry volume. Categories (Music, Sfx, UI, Voice, Ambient) each have a volume and — for Master, Music, and Sfx — a mute toggle in settings. AudioSettings.PoolSize controls how many pooled AudioSource components serve one-shots. The included game palette installs 32 voices; keep at least 24 for dense currency/confetti sequences.

Haptic Feedback

Vibration with a pattern library, expressed as duration/amplitude pairs that translate to Android vibrator waveforms and iOS haptic calls. The static Haptics facade forwards to the registered IHapticService.

Pattern library

HapticPatterns ships: Tick, LightTap, MediumTap, HeavyThud, LongBuzz, DoubleTap, TripleTap, Heartbeat, RampUp, RampDown, Success, Error, CoinPickup, LevelComplete, GameOver, and Explosion. HapticPattern assets let designers author their own patterns without touching code — create one via Assets ▸ Create ▸ HLK ▸ Haptics ▸ Pattern, and a few sample patterns ship under Presets/Haptics. (HapticClip is the runtime struct these compile down to, not an authorable asset.)

Backends & modes

Virtual Economy

A persisted wallet for the game's currencies. CurrencyId enumerates Coins (soft) and Gems (premium); balances are stored by stable string key so saved data survives refactors. EconomyService wires the wallet to persistence and registers it as IWallet.

UI companions: CurrencyHud binds a live balance readout, and CoinGatherEffect flies collected coin sprites toward the HUD counter before the credit lands.

Localization

Key-to-string translation with per-locale tables. A LocalizationTableSet groups one LocalizationTable per locale code; LocalizationService picks the active locale (persisted across sessions under HLK.Locale) and falls back gracefully — missing keys return the supplied fallback or the key itself instead of blowing up.

For scene text, add the LocalizedText component next to a label: it looks up its key on enable and re-resolves automatically when the locale changes. Sample tables for en and fr ship with the kit, and the preset generator can scaffold a table set under Presets/Localization/.

In-App Purchases

Store-neutral purchasing through IAPBridge. Products are authored as IAPProduct assets collected into an IAPCatalog; each product carries a PurchaseReward hook that grants its contents on purchase, restore, or coupon redemption — one grant path for all three.

Product kinds & failure reasons

IAPProductKind: Consumable, NonConsumable, Subscription. Failures normalize to PurchaseFailureReason: UserCancelled, UnknownProduct, AlreadyOwned, PaymentDeclined, StoreNotReady, and more.

Backends

Purchases Pro

The advanced purchasing layer on top of the base flow: subscription tiers, receipt validation, limited-time visibility, and coupon mappings, all configured in the IAPPro settings section.

Subscriptions

Tiers are declared as SubscriptionTier rows (product id, tier name, rank); a higher rank satisfies checks for lower ones. SubscriptionGraceDays (default 3) keeps perks alive briefly past expiry, and ReverifyOnAppStart re-checks receipts each launch. GetSubscriptionOfferText(productId) surfaces free-trial / introductory / promotional / win-back marketing copy from the product's SubscriptionOffers.

Receipt validation

Enable EnableServerValidation and point ValidatorEndpoint at your server. ValidationFailurePolicy decides what an unverifiable purchase does: Block (withhold the grant), GrantOptimistically, or Defer (queue and re-check via ReverifyQueuedAsync()).

Limited-time products & coupons

LimitedTimeProducts constrain when a product may be bought — IsWithinVisibilityWindow(productId) tells the shop UI whether to show it, and NotifyOfferSeen(productId) records an impression. Coupons map redeem codes to products for RedeemCouponAsync; each code redeems once per device.

Ads & Mediation

One ad API across every network. AdService resolves an IAdBackend from the configured mediation provider, checks pacing and the ad-free entitlement before every intrusive show, and normalizes the outcome into AdShowResult / RewardedResult.

Placements

AdPlacement is a ScriptableObject naming one ad slot: an id, an AdUnitKind (Rewarded, Interstitial, Banner, AppOpen, RewardedInterstitial, Native), and optional per-placement pacing overrides (min interval, session/day caps, quiet-first-levels). Rewarded placements can opt out of the ad-free entitlement via IgnoreNoAdsEntitlement — players who paid to remove ads usually still want to choose rewarded ones.

Outcomes

Providers

AdMode selects Dummy (the MockAdBackend renders a fake ad overlay in-engine — no SDK at all), Test (real SDK, test units), or Production. AdsDiagnosticsOverlay can be toggled in development builds to watch fill, pacing decisions, and revenue callbacks live.

Ads Pro & Ad-Free

Extended formats, global frequency capping, and the paid ad-removal path, configured in the AdsPro settings section.

Extended formats

Opt-in toggles enable App-Open ads (with a minimum interval, first-run suppression, and optional on-resume showing), rewarded interstitials, and native ads — each with per-platform test/production unit ids. Preload switches (PreloadRewardedOnStart, PreloadInterstitialOnStart, ReloadAfterShow) keep inventory warm.

Frequency capping

AdPacing enforces the global rules before any intrusive ad shows: InterstitialMinIntervalSec (default 60), InterstitialMaxPerSession and InterstitialMaxPerDay (0 = uncapped), NoInterstitialsBeforeLevel, and a boot grace window. Feed it progress via Pacing.SetLevel(n) / AdvanceLevel(). A blocked show resolves as Suppressed with the failing rule in Reason.

Ad-free entitlement

The entitlement flag defaults to the key hce.entitlement.ad_free (AdFreeEntitlementKey). Three switches decide what it silences: AdFreeHidesBanners, AdFreeHidesInterstitials, and AdFreeHidesAppOpen — all on by default. Rewarded ads keep working unless a placement says otherwise. Impression-revenue forwarding (EnableImpressionRevenue) publishes paid events through AdRevenueHub for attribution and analytics.

Shop & Cosmetics

A catalog-driven store for currency-priced, ad-unlocked, IAP-linked, gated, and cooldown-gift items, with an equip system that applies cosmetic effects to scene objects.

Item anatomy

A ShopItem asset combines an id, display info, a ShopItemKind (NonConsumable / Consumable), and exactly one acquisition style:

• Currency-priced — a CurrencyId plus Price; the wallet is debited.
• Rewarded-ad unlock — UnlockByRewardedAd; granted after a completed rewarded view.
• Real-money — IapProductId links the item to an IAP product.
• Cooldown gift — ClaimCooldownSeconds > 0; claimable for free on a timer (GetCooldownRemaining feeds the countdown label).
• Gated — PrerequisiteId requires owning another item first.

Cosmetics

Equippable items reference a CosmeticEffect: MaterialSwapEffect, MeshSwapEffect, or ChildToggleEffect. Equipping is exclusive per EquipTarget, and ShopItemView renders one catalog entry with its price, state, and buttons. Ownership persists through PlayerPrefsShopStore.

Timed Offers

Limited-window promotions that appear for the right player at the right moment. Offers are OfferDefinition assets in an OfferCatalog; the service tracks eligibility, impressions, and lifetime caps per offer.

Offer kinds

Presentation fields cover discount display: marketing price tags, an original-price strikethrough, DiscountPercent, banner art, and an accent color. MaxLifetimeShows (default 3) and CooldownSeconds throttle repeats; state persists per offer and can be cleared with ResetState / ResetAllState during QA.

Daily Rewards

A login-streak reward loop ("starter gifts"): the player claims one gift per UTC day from a designer-authored StarterGiftSchedule, streaks advance the ramp, and a rewarded ad can multiply the claim.

Streaks & grace

Claiming on consecutive UTC days grows CurrentStreak. Missing days is judged against StarterGifts.GraceDays: a gap is forgiven while the number of fully-missed days stays at or below the grace allowance; one more and the streak resets to zero so the next claim restarts at day 1. The default grace is 0 — strictly consecutive. Re-entering the app on the same day is always a no-op.

Stock schedule

The generated preset is a looping 5-day cycle (LoopAfterLastDay = true):

Boosted claims & UI

ClaimBoosted(multiplier) multiplies currency amounts; ClaimWithAdBoost runs an IRewardedAdGate first (wired to the DoubleAdPlacement setting) and claims only on completion. StarterGiftPanel, StarterGiftTile, and StarterGiftCountdown render the calendar — each tile reflects a GiftDayState of Claimed, Today, or Locked. Preview helpers (PreviewCurrent, PreviewDay, PreviewUpcoming) never mutate state.

Clock hardening

DailyCooldownService offers a simpler stamped-cooldown variant with a paid retry (TryPaidRetry). To resist device-clock rollback, set a TimeProbeUrl: RemoteHttpTimeSource estimates server UTC from a single HTTP HEAD request's Date header — no payload, no identifiers. Leave the field empty to rely on the device clock only.

Reward Wheel

A weighted prize wheel split into headless selection and cosmetic spin. The outcome is decided by weight before the wheel ever moves; the animation then lands on the pre-selected slice, so presentation can never desync from the grant.

Slice data

A WheelSliceDatabase asset holds the slices. Each WheelSlice carries RewardId, Amount, Weight (relative probability; 0 or negative excludes the slice), icon, label, an optional localization key, and a wedge color. Selection uses WeightedSelector; SampleDistribution(n) returns an empirical histogram so you can sanity-check drop rates, and UseFixedSeed(seed) makes outcomes reproducible for tests.

Spin presentation

WheelSpinSettings.Default spins for 3.2 seconds over 5 full turns with a cubic-out deceleration. WheelSpinner.ComputeTargetAngle converts the winning index into a final rotation (with jitter inside the wedge), and SegmentTicker raises a Tick event each time the pointer crosses a slice boundary — hook it to a click sound and a light haptic for a convincing ratchet. WheelView builds the wedge visuals from the database.

Chest & Slot Minigames

Two compact reward minigames sharing one RNG and reward-granting core (MinigameRng, WeightedPicker, MinigameRewardGranter). Both are headless services you can drive from any UI.

Chests

ChestConfig defines the tier list (each tier has an id, display name, key cost, and a weighted drop table) plus ChestsToShowAtOnce (default 3) and whether duplicate tiers may appear on one board. For animated reveals, split the flow: RollDrop decides the prize, your animation plays, then GrantRolled pays it out.

Slot machine

SlotMachineConfig defaults: 3 reels, a spin cost of 10 coins, a 1.2-second spin with 0.3-second reel stagger. Symbols are weighted; payouts map symbol combinations to rewards. Validate(problems) on either config lists authoring mistakes before they reach players.

Quests

Windowed goal tracking driven by the same event names you already emit for analytics. Quests are QuestDefinition assets in a QuestCatalog; the service scores incoming events against them, tracks per-window progress, and pays currency on claim.

Windows & matching

QuestKind scopes a quest to a window: Daily, Weekly, Event, or Permanent. When the window rolls over (UTC), progress resets automatically. A definition matches by EventName, counts either occurrences or a numeric event property (QuestMatchKind + PropertyName), can require a property filter (ConditionPropertyName / ConditionValue), and finishes at Goal. Rewards are a CurrencyId + RewardAmount.

Advance(questId, amount) progresses a quest directly when you'd rather not go through events. Progress events: ProgressChanged, Completed, Claimed, and a coarse Changed.

Battle Pass

A seasonal XP ladder with parallel free and premium reward tracks. XP arrives from gameplay events or direct grants; premium unlocks through an IAP product; every tier holds up to two claimable rewards.

Season configuration

BattlePassConfig holds the SeasonId (changing it starts a fresh season), the tier ladder (each BattlePassTier sets an XP threshold and a reward per track), the premium product id, and the XP feed: a CSV of qualifying event names (or AcceptAllEvents), with XpSource choosing between a flat XpPerEvent and reading a numeric event parameter. Reward kinds cover currency and item grants — item fulfillment routes through your IBattlePassItemFulfiller.

Events: XpChanged, TierAdvanced, RewardClaimed, ItemRewardGranted, PremiumUnlocked, Changed.

Wiring it up

• Unlock premium on purchase. Nothing unlocks the premium track automatically — when the IAP for Config.PremiumProductId succeeds, call Services.Resolve<IBattlePassService>().UnlockPremium() from your purchase-success handler (and again after a restore).
• Currency rewards need an economy adapter. Depositing currency-kind rewards routes through an IBattlePassEconomy registered in the service registry. A wallet-backed adapter ships at bootstrap whenever an IWallet is present; if you swap the wallet out, register your own IBattlePassEconomy or currency rewards silently no-op.
• XP from gameplay events. A bus→IngestEvent forwarder ships at bootstrap, so events you emit on the analytics bus that match the season's EventNamesCsv (or AcceptAllEvents) drive XP. You can still call GrantXp / IngestEvent directly.

Energy System

A regenerating lives/energy meter that gates level attempts, refills over wall-clock time (including while the app is closed), and sells refills through ads or IAP.

Defaults

Reconcile() recomputes regeneration against elapsed real time — the EnergyFocusWatcher calls it on app focus when RecalcRegenOnFocus is enabled, so returning players find the hearts they earned while away. Regeneration stops at Max, and every top-up path is clamped to Max as well — Refill / RefillToMax discard any excess and return the number of units actually added.

Content Gating

Declarative lock/unlock rules for buttons, levels, and features. Designers author UnlockCondition assets, attach an UnlockGate component to the UI, and the gate keeps the target's interactable state, label, and locked overlay in sync.

Condition types

UnlockGate re-evaluates on a timer (default every 0.5 s) and raises StatusChanged. With ConsumeOnClick enabled, clicking the unlocked target runs the condition's consume step. Only stateful conditions mutate here: a CooldownUnlockCondition re-stamps its timer on consume. Currency conditions do not spend on consume — they only check affordability, so your game must perform the actual wallet debit itself.

Player state flows through an IPlayerContext. The built-in DefaultPlayerContext bridges the wallet and save flags automatically, but the level number is not auto-wired — with no level provider it reports 0, so a LevelUnlockCondition stays locked (unless its threshold is 0). Supply a level provider, or register your own context, before level gates work:

Rate-Us Prompts

Store review requests with strict throttling, an optional soft pre-prompt, and platform-correct backends. The service tracks sessions and prompt history so review dialogs appear rarely and only to players who have had time to enjoy the game.

Throttle gates

Soft pre-prompt

When PrePromptEnabled is on (default), a friendly in-game question runs before the real store dialog, protecting your quota from players likely to decline. The default copy — title "Having fun so far?", body "Would you mind rating us?", buttons "Rate it" / "Maybe later" — is fully editable in settings. Provide the dialog UI by assigning a RateUsSoftPrompter delegate via SetSoftPrompter — for example route it through the Popup Stack.

Backends

RateUsMode: Disabled, Dummy (logs, no dialog), or Production — Android uses Google Play In-App Review, iOS uses the system review controller, and GetGateState() plus ResetGates() support QA. Fill in AndroidPackageName / IOSAppId for the store-page fallback link.

The Android backend (AndroidRateUsBackend) reaches the Play In-App Review library entirely by reflection, so no scripting define or managed reference is needed to compile. To make the native stars popup actually fire on device, add the Play review Gradle dependency com.google.android.play:review:2.0.1 — the Rate Prompt tab has a one-click button that inserts it into your Android mainTemplate.gradle. Without that dependency the request reports "unavailable" at runtime and the service falls back to the Play Store listing.

Local Notifications

Schedule on-device reminders — energy refilled, gift ready, streak about to break — with permission handling on both mobile platforms and a log-only backend everywhere else.

NotificationMode: Disabled, Dummy (log-only; the editor default), or Production — the mobile backend requires Unity's Mobile Notifications package and HLK_MOBILE_NOTIFICATIONS. Only the default hce_default Android channel is created automatically; there is no settings list of extra channels — supply a custom category/channel per notification via NotificationRequest.CategoryId. The iOS alert/badge/sound options do come from settings.

Game Services

Leaderboards, achievements, and platform sign-in behind one interface. Your code speaks in logical ids; a GameServicesCatalog asset maps each one to its Game Center and Play Games store ids, so gameplay code never branches per platform.

LeaderboardScoreFormatter renders scores per the catalog's LeaderboardScoreFormat (Number, TimeCentiseconds, Currency).

Providers

Cloud Save

Synchronizes the local save blob with a per-player cloud slot, with an explicit, configurable conflict policy instead of silent last-writer-wins.

Conflict policies

CloudSaveAutoSync can sync on app pause (default on) and on currency changes (default off). Results carry a CloudSaveStatus — Ok, ConflictResolved, ConflictUnresolved, NotSignedIn, NetworkError, QuotaExceeded — plus which SyncDirection actually happened.

Providers

Consent & Privacy

Privacy consent for two dimensions at once: regional regulation (GDPR-style consent via Google's UMP) and Apple's App Tracking Transparency. The rest of the kit asks one question — CanRequestPersonalized — and the consent module answers it.

ConsentMode: Disabled, Dummy (returns the forced DummyOutcome from settings — handy for QA), or Production using Google UMP behind HLK_UMP; on iOS the ATT prompt is additionally gated by HLK_ATT. ConsentGate lets other bootstraps defer work until consent resolves.

Push Messaging

Remote push notifications with token lifecycle, topic subscriptions, and an in-editor simulator so you can build the receiving side without a backend.

PushMode: Disabled, Dummy, or Firebase — the FCM backend compiles behind HLK_FIREBASE_MESSAGING and requires the Firebase Messaging package plus your platform config files.

Social Sharing

Native share sheets for text, links, images, screenshots, email, and SMS, wrapped in the static Share facade. Every call resolves to a ShareResult that distinguishes success, cancellation, and failure with a reason.

SharingMode: Disabled, Dummy (logs the request), or Native behind HLK_NATIVE_SHARE. Share attempts and outcomes can be mirrored onto the analytics bus.

In-App Web View

Open web content — privacy policy, support portal, seasonal event page — inside the app instead of bouncing players to an external browser. Supports raw HTML as well as URLs, with a JS message bridge back into the game.

WebViewMode: Dummy, Disabled, or Native. Dummy is a system-browser fallback with an emulated lifecycle — URLs (and HTML, written to a temp file://) are handed to the OS browser via Application.OpenURL and the "view" reports synthetic page-started/finished/closed events; it is not an in-engine panel.

Native binds to the UniWebView plugin. To use it: import the UniWebView asset into the project, enable the HLK_NATIVE_WEBVIEW scripting define, and ensure HLK.Runtime.asmdef references the UniWebView assembly (this reference already ships in the kit's asmdef).

Deep Links

Routes custom-scheme and universal links into structured payloads. Links that arrive before your handler subscribes are buffered, so cold-start links are never lost.

Declare your schemes and App/Universal Link hosts in settings (CustomSchemes, UniversalLinkHosts); the engine backend hooks Unity's application deep-link events on device.

Remote Config

Server-tunable values with typed accessors and offline-safe defaults. Seed key/value defaults in settings; they answer immediately and act as the fallback whenever a fetch fails or a key is missing.

Providers

The backend factory preflights each provider and refuses to promote past Dummy until its prerequisites are met:

• Firebase — the Firebase Unity SDK (Remote Config), the platform config files (google-services.json on Android, GoogleService-Info.plist on iOS), and the HLK_FIREBASE_REMOTE_CONFIG define. HLK.Runtime.asmdef references the Firebase.RemoteConfig assembly.
• Unity Gaming Services — the project linked to a UGS org, both the com.unity.remote-config and com.unity.services.authentication packages (UGS Remote Config signs in anonymously first), and the HLK_UGS_REMOTE_CONFIG define. HLK.Runtime.asmdef references the Unity.Services.RemoteConfig and Unity.Services.Authentication assemblies.

App Updates

Detect newer builds and walk players through updating — via Google's in-app update flows on Android, a store version check on iOS, and a simulated backend for QA everywhere.

AppUpdateMode: Disabled, Simulated (settings choose the forced availability and version), AppStoreVersionCheck (queries Apple's public iTunes Lookup endpoint and deep-links to the store listing — no SDK needed), or PlayInApp behind HLK_PLAY_APP_UPDATE. UpdateAvailability.CriticalUpdate supports force-update gates; VersionComparer handles semantic version ordering.

Attribution

Install-source measurement (MMP) integration: where did this player come from, and which campaigns produce payers. Ships with an AppsFlyer backend and a fully offline in-memory stand-in.

AttributionMode: Disabled, Dummy (in-memory), or Production — AppsFlyer behind HLK_APPSFLYER with your dev key. On iOS the SDK start can wait up to AttPromptTimeoutSeconds (default 60) for the App Tracking Transparency prompt; conversion data can be forwarded onto the analytics bus.

Crash Reporting

Uncaught-exception capture, breadcrumbs, and custom keys behind a swappable backend. The static facade on CrashReporterService keeps call sites one line long.

CrashReporterMode: Disabled (the fresh-import default — nothing is captured), LogOnly (console echo; select this to see reports without an SDK), or Production via Firebase Crashlytics behind HLK_CRASHLYTICS. Settings choose whether uncaught exceptions and error-level logs are reported, and can stamp a build label on every report.

Native Dialogs

OS-styled alerts, confirmations, action sheets, text prompts, and short toasts through one awaitable API — with a uGUI-rendered fallback so the same calls work in the editor and on unsupported platforms.

NativeUIMode: InEngine (the built-in renderer) or Native behind HLK_NATIVE_UI — with UseInEngineWhenUnsupported (default on) falling back automatically per dialog type.

Runtime Permissions

Cross-platform permission checks and requests for camera, microphone, photo library (read and add), and when-in-use location, normalized into one PermissionState model.

PermissionsMode: Auto, Simulated (always auto-grants — no OS prompt), or Native behind HLK_NATIVE_PERMISSIONS. Build post-processors inject the iOS usage-description strings you enter in settings into Info.plist, and align the Android manifest — no manual plist editing.

Analytics Pipeline

A fan-out event bus: game code emits once, every attached IAnalyticsSink receives the event. One misbehaving sink can't take the pipeline down — sink exceptions are contained per dispatch.

Sinks

AnalyticsMode gates the fan-out: Disabled, ConsoleOnly (default), or Live (console plus every enabled provider). Other modules publish onto the same bus when their "bind to analytics" switches are on — quests, offers, IAP funnel steps, ad outcomes, sharing results, and game-services submissions emit automatically. The battle pass emits its outbound telemetry the same way, but its inbound XP relies on a bus→IngestEvent forwarder (shipped at bootstrap) so gameplay events on the bus also drive the pass — see the Battle Pass section.

Going live (UGS / Firebase)

The stand-in sinks need no setup, but the real providers do:

• Unity Analytics (UGS) — link the project in Project Settings ▸ Services (UGS requires a Cloud project id), install the com.unity.services.analytics UPM package, and add HLK_UNITY_ANALYTICS.
• Firebase Analytics — import the Firebase SDK, drop google-services.json (Android) / GoogleService-Info.plist (iOS) under Assets, and add HLK_FIREBASE.

Then switch the mode to Live and enable the matching sink. The Analytics tab checks each of these prerequisites and reports the effective backend.

Popup Stack

Modal dialogs with serialized queueing, stacking, a shared dimming backdrop, and input blocking. Popups are prefabs whose root implements IPopupView — derive from PopupBase and the animation/close plumbing is handled for you.

Ready-made views: MessagePopup (title/body/OK via MessagePopupArgs) and ConfirmPopup (accept/cancel with an Action<bool> choice callback). A popup can opt out of backdrop dimming or timescale independence per prefab; the overlay canvas sorts at order 30000 so popups clear regular UI.

Toast Messages

Transient, non-blocking notices shown strictly one at a time in arrival order. Each toast carries a kind for coloring and its own duration; the queue drains on unscaled time, so toasts keep flowing while the game is paused.

Kinds: Info, Success, Warning, Error. With no view bound (early boot, headless tests) messages are logged instead and the queue still advances — a later-bound view is never flooded with a backlog. Drop a ToastView prefab in the scene and ToastBinder connects it to the service.

UI Widgets

Small, dependency-free components that cover the recurring polish work of mobile UI:

Toolset Window

The kit's one configuration surface. Open it via Tools > HLK > Open Toolset (or Tools > HLK > Guided Setup — same window; the toolset is the setup flow). It binds directly to the HLKSettings asset and remembers your last tab.

Tab layout

Tabs are arranged in two rows — the core row first, the Pro row after:

What the tabs give you beyond fields

• SDK probes — each vendor-backed tab detects whether the SDK and its scripting define are actually present, and shows what the effective backend will be.
• Pre-flight checks — production-readiness banners (e.g. missing ad unit ids) before you ship with placeholder values.
• Helper actions — one-click steps like adding the Android VIBRATE permission, always behind an explicit confirmation dialog.
• Asset creation — buttons to generate the preset assets for data-driven modules (also reachable in bulk via Tools > HLK > Generate Starter Config Assets).

Cheat Console

An on-screen QA console for the actions testers repeat all day. Its compile-time gate keeps releases clean: with HLK_CHEATS defined you get the live CheatService plus the console overlay; without it, an inert NoOpCheatService is registered instead, so any code resolving ICheatService still works — it just refuses politely.

Opening the console

• Desktop / editor: the toggle key — BackQuote (`) by default.
• Device: press and hold with 3 fingers for 1 second.

Both gestures, keyboard shortcuts, grant amounts (defaults: 1000 coins / 100 gems), and currency ids are configured in a CheatBindings asset loaded from Resources/HLK/CheatBindings.

Built-in actions

CheatActionId: GrantCoins, GrantGems, ResetDailyStreak, ClearShopOwnership, WipeAllData — plus ReloadActiveScene() on the service. When compiled in, a warning is logged every launch as a reminder to strip the define from release builds.

Scripting Defines

Vendor SDK code never compiles until you opt in. Each integration sits behind an HLK_* define; install the vendor SDK, make sure the define is set, and the real backend replaces the stand-in. How the define gets set depends on how the SDK is distributed:

• UPM-package integrations define themselves. These sit behind a version define in HLK.Runtime.asmdef, so installing the package automatically adds the define — no manual step: HLK_ADMOB, HLK_UNITY_PURCHASING, HLK_UNITY_ANALYTICS, HLK_FIREBASE, HLK_CRASHLYTICS, HLK_FIREBASE_MESSAGING, HLK_MOBILE_NOTIFICATIONS, HLK_APPSFLYER, HLK_LEVELPLAY, HLK_UNITY_ADS, and HLK_ATT.
• Everything else is set manually. SDKs delivered as .unitypackage / asset-store imports (and the kit's own compile-time switches) have no version define, so you add the define yourself — via the relevant Toolset tab, or Project Settings → Player → Scripting Define Symbols. This covers HLK_APPLOVIN_MAX, HLK_PLAY_GAMES_SERVICES, HLK_PLAY_GAMES_SAVE, HLK_GAME_CENTER, HLK_NATIVE_SHARE, HLK_ICLOUD, HLK_NATIVE_PERMISSIONS, HLK_NATIVE_WEBVIEW, HLK_NATIVE_UI, HLK_UMP, HLK_PLAY_APP_UPDATE, HLK_FIREBASE_REMOTE_CONFIG, HLK_UGS_REMOTE_CONFIG, HLK_CHEATS, and HLK_LOG_VERBOSE.

Troubleshooting

Issues are grouped by module. Diagnostic logging helps with nearly all of them: enable VerboseLogging on the General tab and watch for [HLK]-tagged lines.

Core & boot

Save & cloud

Monetization

LiveOps

Platform services

UI, audio & debug

Currency Icon Setup

CurrencyIcons.Get(CurrencyId) first uses the icon assigned to the active CurrencyCatalog. If no catalog icon is assigned, it falls back to Resources.Load<Sprite>("HLK/CurrencyIcons/<CurrencyId>").

For drop-in icons, create Resources/HLK/CurrencyIcons/ and add files such as Coins.png and Gems.png. Each filename must match its CurrencyId enum member exactly. Import the image as Sprite (2D and UI), Single mode, with mipmaps and Read/Write disabled.

Lookups, including misses, are cached. Call CurrencyIcons.InvalidateAll() after changing icon art or CurrencyIcons.Invalidate(id) to refresh one currency. A fresh play-mode session starts with an empty cache.

Portable Power-Ups

The PowerUps module keeps definitions, catalogs, inventory state, effect handlers, the runtime bar, buttons, tutorial popup, setup tools, shared artwork, and the sample Rainbow Release preset together without embedding game-specific behavior in the definitions.

Add a power-up

1. Open Tools > HLK > Power-Ups > Setup & Catalog.
2. Choose a permanent ID and display name, then create the definition.
3. Assign its center icon and tutorial illustration. The shared slot frame can normally stay unchanged.
4. Implement IPowerUpEffectHandler in the host game and register it while the gameplay scene is active.
5. Run Tools > HLK > Power-Ups > Validate.

The default PlayerPrefsPowerUpStateStore supports offline inventory. Install an account or cloud implementation of IPowerUpStateStore through PowerUpServices.SetStateStore(...). Catalog ordering, enable flags, duplicate-ID validation, and an optional display limit control how definitions appear; a zero display limit shows all enabled definitions in the horizontal scroller.

Release Notes

2.0.0

• Added the independently portable Power-Ups module with scalable catalog, injectable state, generic effect registry, horizontal runtime bar, tutorial template, editor creator, and validation.
• Added daily, weekly, event, and permanent quests; seasonal battle-pass tracks; regenerating energy; and timed offers.
• Added game services, cloud save, push messaging, consent, deep links, app-update prompts, and typed remote config.
• Added catalog-based IAP, mediation-ready ads, and shop items for currencies, ads, unlock gates, and real-money products.
• Added starter gifts, reward wheel, slot and chest minigames, rate prompts, and local notifications.
• Added queued toasts, modal popups, haptics, pooled audio, wallet economy, versioned saves, localization, analytics, sharing, web view, runtime permissions, attribution, crash reporting, and toon shaders.

Licenses & Notices

Robert Penner's Easing Equations

The standard easing constants and curve shapes used by Runtime/Core/Easing.cs, including the back-overshoot, elastic-period, and bounce-segment parameterizations, are derived from Robert Penner's easing equations and are used under the BSD License.

Support

Stuck on something this manual doesn't cover? Reach out — real answers from the developer, usually within two business days.

• Email: satisvizion@gmail.com

To get the fastest turnaround, include:

• Unity version, target platform, and render pipeline;
• the module and mode involved (e.g. "Ads, LevelPlay, Production");
• console output with VerboseLogging enabled — the [HLK] lines around the failure are usually enough to pinpoint it;
• which HLK_* defines your build sets.

Bug reports that arrive with a minimal reproduction scene get priority. Feature requests are welcome too — a lot of this kit exists because someone asked.