Chương 7: Hạ tầng & UI Services

Khám phá bộ công cụ hạ tầng cốt lõi (Core Infrastructure) của MGW SDK: Quản lý vòng đời dịch vụ qua ServiceLocator và App facade, quản lý hộp thoại chuyên nghiệp với DialogBase, DialogService và DialogQueue, chuyển cảnh mượt mà qua SceneLoader, che chắn màn hình với UIOverlay, lưu trữ dữ liệu an toàn bằng LocalStorage, cùng các tiện ích âm thanh, rung, coroutine và log runtime.

1. Mục đích & Mô hình tư duy (Mental Model)

Trong phát triển game Unity, các vấn đề phổ biến nhất thường bắt nguồn từ kiến trúc hạ tầng: việc lạm dụng quá nhiều static Instance singleton rải rác, các MonoBehaviour sống dai dẳng không rõ vòng đời, logic hiển thị popup chồng chéo gây lỗi raycast, hay dữ liệu PlayerPrefs bị ghi đè không kiểm soát.

Tầng TapBrain.Core được thiết kế theo 3 nguyên tắc nền tảng:

• Plain C# Services làm nòng cốt: Hầu hết dịch vụ hạ tầng (như SceneLoader, DialogService, LocalStorage, AudioService) là các lớp C# thuần túy, không kế thừa MonoBehaviour. Điều này giúp loại bỏ rác component trong Hierarchy, dễ viết unit test và kiểm soát vòng đời tường minh.
• Một MonoBehaviour dịch vụ duy nhất làm cầu nối (CoreHost): SDK chỉ có một MonoBehaviour dịch vụ là CoreHost, gắn trên GameObject [Core], để chạy coroutine và lắng nghe sự kiện vòng đời ứng dụng (Pause, Quit, Back button). Ngoài ra Core tạo thêm hai Canvas bền vững sinh bằng code là [Dialogs] (sorting order 1000) và [CoreOverlay] (sorting order 30000), không chứa MonoBehaviour logic.
• Phân định ranh giới đăng ký và truy xuất: Chỉ có Bootstrapper (composition root) và các SDK Module được quyền đăng ký dịch vụ vào ServiceLocator. Mã nguồn game chỉ truy xuất thông qua lối tắt App facade hoặc ServiceLocator.Get<T>().

2. ServiceLocator & App Facade

ServiceLocator: Điểm truy xuất tập trung

Lớp tĩnh TapBrain.Core.ServiceLocator lưu trữ registry của toàn bộ các dịch vụ hệ thống. Khi cấu hình Enter Play Mode tắt tính năng Domain Reload, phương thức nội bộ tự động dọn dẹp static dictionary để chống rò rỉ trạng thái giữa các lần bấm Play.

Lối tắt App Facade cho công việc hằng ngày

Để giảm bớt việc gõ dài dòng ServiceLocator.Get<...>(), SDK cung cấp lớp tĩnh TapBrain.Core.App như một facade nhẹ (thin forwarders). Các thuộc tính này không lưu giữ trạng thái mà chuyển tiếp trực tiếp đến ServiceLocator:

3. Hệ thống Popup: DialogBase & DialogService

Cách tạo một Popup kế thừa DialogBase

Mọi cửa sổ popup trong game đều phải kế thừa từ TapBrain.Core.DialogBase. Lớp này kế thừa MonoBehaviour và bắt buộc có component CanvasGroup để phục vụ hoạt ảnh mờ dần (Fade) và co giãn nhẹ (Scale).

Quy chuẩn bắt buộc: Prefab của popup phải được đặt tại đường dẫn Resources/Dialogs/<Tên_Class>.prefab.

using TapBrain.Core;
using UnityEngine;
using UnityEngine.UI;

namespace MyGame.UI
{
    public sealed class PauseDialog : DialogBase
    {
        // Build index of your own home scene (see File > Build Settings).
        private const int HomeSceneIndex = 1;

        [SerializeField] private Button resumeButton;
        [SerializeField] private Button homeButton;

        protected override void Awake()
        {
            base.Awake(); // mandatory: DialogBase caches its CanvasGroup here
            resumeButton.onClick.AddListener(OnResumeClicked);
            homeButton.onClick.AddListener(OnHomeClicked);
        }

        protected override void OnOpened()
        {
            // Called right after the dialog is activated, before the fade-in animation runs.
        }

        protected override void OnClosed()
        {
            // Called after the fade-out animation ends, right before the GameObject is destroyed.
        }

        private void OnResumeClicked()
        {
            Close();
        }

        private void OnHomeClicked()
        {
            Close();
            App.Scenes.Load(HomeSceneIndex);
        }
    }
}

DialogService (App.Dialogs): Quản lý chồng Popup

DialogService tạo một Canvas riêng biệt mang tên [Dialogs] với sortingOrder = 1000, gắn cờ DontDestroyOnLoad, thiết lập tỉ lệ màn hình chuẩn 1080x1920 (match 0.5). Toàn bộ prefab sau khi tải từ Resources/Dialogs/ sẽ được lưu vào bộ nhớ đệm (cache) để tránh gọi lại Resources.Load nhiều lần.

Enum DialogShowMode quy định cách popup mới tương tác với các popup sẵn có:

• DialogShowMode.Stack (Mặc định): Mở đè lên trên đỉnh. Các dialog nằm dưới vẫn giữ nguyên trạng thái mở (ví dụ: mở hộp thoại xác nhận đè lên trên cửa hàng).
• DialogShowMode.ReplaceTop: Đóng popup ở đỉnh ngăn xếp hiện tại rồi mới mở popup này lên (dùng cho các bước nối tiếp trong một luồng tương tác).
• DialogShowMode.ReplaceAll: Đóng toàn bộ tất cả popup đang mở trước khi hiển thị popup mới (dùng cho các trường hợp khẩn cấp như mất kết nối, bắt buộc cập nhật).

4. Hàng đợi Dialog ưu tiên: DialogQueue

Trong game casual, thời điểm người chơi hoàn thành màn chơi hoặc trở về sảnh thường có rất nhiều popup cần hiển thị: Quà đăng nhập, Thông báo thăng cấp, Rương thưởng, Lời mời đánh giá... Nếu bạn viết một chuỗi lệnh if ... else if ... phức tạp, code sẽ rất dễ gãy vỡ.

DialogQueue giải quyết bài toán này bằng cách hiển thị lần lượt từng popup một (ONE AT A TIME) theo thứ tự ưu tiên (Priority) giảm dần.

Quy tắc hoạt động cốt lõi của DialogQueue

• Xếp lịch xả hàng đợi (Scheduled Drain): Khi bạn gọi Enqueue liên tiếp trong cùng một frame, hệ thống gom lại và chờ sang frame kế tiếp mới bắt đầu sắp xếp và hiển thị popup có độ ưu tiên cao nhất.
• Kiểm tra điều kiện trước khi mở (canShow): Hàm delegate Func<bool> canShow được đánh giá lại ngay trước thời điểm popup chuẩn bị bung ra. Nếu trả về false, yêu cầu đó sẽ bị bỏ qua.
• Tự động tạm dừng (Pause) thông minh: Hàng đợi sẽ đứng chờ nếu đang có bất kỳ dialog nào mở trên màn hình (kể cả dialog mở bên ngoài queue), khi đang có quảng cáo toàn màn hình (Fullscreen Ad) đang chiếu, hoặc khi hàng đợi đang bị gọi Pause().
• Vòng đời gắn chặt với Scene: Bạn nên tạo DialogQueue trong Start() và gọi Dispose() trong OnDestroy(). Ngoài ra, hàng đợi tự động hủy (Dispose) ngay khi sự kiện SceneLoading phát ra, ngăn không cho các popup tồn đọng bung ra trong lúc scene đang bị giải phóng.

5. Chuyển cảnh với SceneLoader & Loading Screen

SceneLoader (App.Scenes): Chuyển cảnh có hiệu ứng che mờ

Mọi thao tác chuyển màn hình trong game đều được thực hiện qua App.Scenes (lớp TapBrain.Core.SceneLoader), tuyệt đối không gọi trực tiếp SceneManager.LoadScene. SceneLoader tích hợp sẵn việc làm mờ màn hình (Fade Out), tải bất đồng bộ (Async Load), cập nhật tiến trình và làm sáng trở lại (Fade In).

Cơ chế hoạt động của LoadingScreen

Trong scene khởi động (Build Index = 0), GameObject giao diện gắn script TapBrain.Core.LoadingScreen. Thành phần này chỉ đóng vai trò View hiển thị tiến trình, hoàn toàn không chứa logic khởi tạo SDK (logic khởi tạo nằm trong InitPipeline của Bootstrapper).

Các trường SerializedField cấu hình trên LoadingScreen:

• progressFill (Image): Thanh trượt hiển thị phần trăm từ 0 đến 1.
• progressText (TextMeshProUGUI): Nhãn text hiển thị tiến độ dạng "0%" - "100%".
• versionText (TextMeshProUGUI): Tự động điền "v" + Application.version khi khởi động.
• nextSceneBuildIndex (int): Chỉ số build index của scene game đầu tiên cần mở sau khi tải xong (mặc định là 1, thường là sảnh Home).

Trong quá trình chờ, LoadingScreen tham chiếu thông số CoreConfig.minLoadingSeconds (mặc định 1.5 giây). Dù pipeline của SDK hoàn thành nhanh đến đâu, thanh tải vẫn di chuyển mượt mà tối thiểu đủ số giây này để tránh giật hình, sau đó chuyển giao sang SceneLoader.Load(nextSceneBuildIndex).

6. UIOverlay: Màn che, Blocker & Toast

Lớp TapBrain.Core.UIOverlay (truy xuất qua App.Overlay) quản lý một Canvas đỉnh cao nhất mang tên [CoreOverlay] với sortingOrder = 30000. Toàn bộ canvas này được sinh bằng code C#, hoàn toàn không phụ thuộc vào bất kỳ prefab nào nên luôn tồn tại xuyên suốt mọi scene.

7. Lưu trữ dữ liệu với LocalStorage

Lớp tĩnh TapBrain.Core.LocalStorage là wrapper mỏng, có kiểu, bọc quanh PlayerPrefs của Unity. Lớp này không tự thêm tiền tố cho khóa: quy ước core./game. do lập trình viên tuân thủ. Các hàm Set* không tự gọi Save(); CoreHost tự gọi LocalStorage.Save() khi ứng dụng Pause và Quit.

Quy ước phân vùng tiền tố khóa (Key Prefixes)

• Tiền tố core.: Dành riêng cho toàn bộ các thiết lập nội bộ của SDK (ví dụ: core.user_id, core.remove_ads, core.sound_on, core.music_on, core.haptic_on). Phía game tuyệt đối không ghi đè vào các khóa này.
• Tiền tố riêng của game (ví dụ game.): Toàn bộ dữ liệu của dự án game (như số vàng game.coins, màn chơi hiện tại game.current_level, túi đồ) bắt buộc phải bắt đầu bằng tiền tố riêng của game để tránh mọi nguy cơ xung đột.

Bảng phương thức LocalStorage

8. Âm thanh (AudioService) & Rung phản hồi (HapticService)

AudioService (App.Audio)

Hệ thống âm thanh được quản lý bởi TapBrain.Core.AudioService gắn trên GameObject gốc [Core] với 2 AudioSource riêng biệt: một kênh lặp vô tận dành cho nhạc nền (Music) và một kênh phát một lần cho hiệu ứng âm thanh (SFX).

• SoundOn (bool, mặc định true): Bật/tắt SFX; SoundOn = false làm PlaySfx không phát gì. Tự động lưu giá trị vào khóa core.sound_on.
• MusicOn (bool, mặc định true): Bật/tắt nhạc nền. Chỉ mute kênh nhạc (clip vẫn được đặt và Play()), bật lại sẽ nghe tiếp ngay. Tự động lưu giá trị vào khóa core.music_on.
• PlaySfx(AudioClip clip, float volume = 1f): Phát hiệu ứng âm thanh một lần nếu SoundOn == true.
• PlayMusic(AudioClip clip, float volume = 1f): Đặt clip và phát nhạc nền lặp vô tận. Nếu clip đó đang phát thì bỏ qua không phát lại từ đầu.
• StopMusic(): Dừng phát nhạc nền ngay lập tức.
• SetPausedByAd(bool paused): Gán AudioListener.pause = paused. Hàm này do MaxAdsService (Provider MGW) gọi quanh quảng cáo toàn màn hình; game không nên gọi trực tiếp. Provider SayKit không gọi hàm này.

HapticService (App.Haptic)

Dịch vụ rung TapBrain.Core.Services.HapticService mang lại trải nghiệm phản hồi xúc giác tinh tế mà không cần cài đặt thêm plugin bên thứ ba:

• Trên iOS: Tích hợp trực tiếp với bộ phát xúc giác UIFeedbackGenerator của hệ điều hành thông qua plugin HapticFeedback.m.
• Trên Android: Gọi vibrate(ms) của dịch vụ Vibrator với độ dài tính bằng mili-giây theo từng HapticType (bảng dưới).
• Trong Editor và nền tảng khác: Play() không làm gì.

Enum TapBrain.Core.Services.HapticType cung cấp 7 mức độ rung:

Thuộc tính App.Haptic.Enabled (lưu tại core.haptic_on) cho phép người chơi bật/tắt toàn bộ tính năng rung trong màn hình cài đặt.

9. CoreHost, UserIdentity & CoreLog

CoreHost: Chạy Coroutine từ lớp Plain C#

Khi thiết kế kiến trúc game theo hướng Plain C#, các service không phải MonoBehaviour sẽ không thể gọi StartCoroutine. CoreHost đóng vai trò là "vật chủ" đại diện duy nhất của SDK:

• Run(IEnumerator routine): Chạy coroutine và trả về đối tượng Coroutine.
• Stop(Coroutine routine): Dừng một coroutine đang chạy nếu đối tượng khác null.
• Delay(float seconds, Action action): Hẹn giờ thực hiện một hành động sau seconds giây thực (sử dụng WaitForSecondsRealtime).
• ApplicationPaused (event Action<bool>): Phát ra khi game bị Pause/Resume. Khi paused = true, SDK tự động gọi LocalStorage.Save() trước khi phát sự kiện ra ngoài.
• ApplicationQuitting (event Action): Phát ra khi game sắp thoát. Tự động gọi LocalStorage.Save().
• BackPressed (event Action): Phát ra khi phát hiện phím KeyCode.Escape (nút Back trên Android). Dùng Input.GetKeyDown của Input Manager cũ, nên Active Input Handling phải là Input Manager (Old) hoặc Both.

UserIdentity: Định danh người dùng đồng bộ

Dịch vụ TapBrain.Core.UserIdentity (truy xuất qua ServiceLocator.Get<UserIdentity>()) sinh ra một mã định danh duy nhất cho mỗi lượt cài đặt game, được dùng chung cho tất cả các mạng phân tích và quảng cáo (Firebase, AppLovin MAX, GameAnalytics, AppMetrica, BI).

• UserId: Chuỗi định danh gồm Unix timestamp (giây) kèm 4 chữ số ngẫu nhiên (ví dụ 17300012349876).
• IsNewUser: Trả về true nếu đây là phiên chạy đầu tiên sau khi cài mới game.
• InstallDateUtc: Thời điểm cài đặt tính theo chuẩn UTC.
• FirstVersion: Phiên bản game lúc người chơi cài đặt lần đầu (Application.version).
• SessionCount: Số lượt khởi chạy ứng dụng (tự động tăng thêm 1 sau mỗi lần mở game).
• DaysSinceInstall: Số ngày đã trôi qua kể từ ngày cài đặt.

CoreLog: Chuẩn hóa xuất bản Log

Lớp tĩnh TapBrain.Core.CoreLog chuẩn hóa định dạng log với tiền tố thẻ [Tag]:

• CoreLog.Verbose: Cờ kiểm soát. Tự động bật nếu CoreConfig.verboseLog == true hoặc đang ở chế độ Debug Build (Debug.isDebugBuild).
• CoreLog.Info(tag, message): Chỉ in ra Console khi cờ Verbose == true (tức CoreConfig.verboseLog bật hoặc là development build). Định dạng: [tag] message. Mọi dòng log mức Info được nhắc trong chương này (ví dụ [Dialog] ... already open, reusing it) đều tuân theo quy tắc này.
• CoreLog.Warn(tag, message): Luôn in cảnh báo ra Console, kể cả bản release.
• CoreLog.Error(tag, message): Luôn in lỗi đỏ ra Console, kể cả bản release.

10. Ví dụ C# Thực tế Hoàn chỉnh

Ví dụ 1: Xây dựng SettingsDialog hoàn chỉnh

Dưới đây là một hộp thoại Cài đặt hoàn chỉnh kế thừa DialogBase, điều khiển đầy đủ âm thanh, nhạc nền, rung phản hồi và mở đánh giá game:

using TapBrain.Core;
using TapBrain.Core.Services;
using UnityEngine;
using UnityEngine.UI;

namespace MyGame.UI
{
    public sealed class SettingsDialog : DialogBase
    {
        [Header("Toggles")]
        [SerializeField] private Toggle soundToggle;
        [SerializeField] private Toggle musicToggle;
        [SerializeField] private Toggle hapticToggle;

        [Header("Buttons")]
        [SerializeField] private Button reviewButton;
        [SerializeField] private Button closeButton;

        protected override void Awake()
        {
            base.Awake();

            // Initial state comes from the SDK; set it before adding listeners so no handler fires.
            soundToggle.isOn = App.Audio.SoundOn;
            musicToggle.isOn = App.Audio.MusicOn;
            hapticToggle.isOn = App.Haptic.Enabled;

            soundToggle.onValueChanged.AddListener(OnSoundChanged);
            musicToggle.onValueChanged.AddListener(OnMusicChanged);
            hapticToggle.onValueChanged.AddListener(OnHapticChanged);

            reviewButton.onClick.AddListener(OnReviewClicked);
            closeButton.onClick.AddListener(Close);
        }

        protected override void OnClosed()
        {
            // Optional here: these listeners live on this dialog's own children and die with it.
            // Unsubscribing is mandatory only for events of longer-lived objects (services, static events).
            soundToggle.onValueChanged.RemoveListener(OnSoundChanged);
            musicToggle.onValueChanged.RemoveListener(OnMusicChanged);
            hapticToggle.onValueChanged.RemoveListener(OnHapticChanged);
            reviewButton.onClick.RemoveListener(OnReviewClicked);
            closeButton.onClick.RemoveListener(Close);
        }

        private void OnSoundChanged(bool on)
        {
            App.Audio.SoundOn = on;
            App.Haptic.Play(HapticType.Selection);
        }

        private void OnMusicChanged(bool on)
        {
            App.Audio.MusicOn = on;
            App.Haptic.Play(HapticType.Selection);
        }

        private void OnHapticChanged(bool on)
        {
            App.Haptic.Enabled = on;
            if (on) App.Haptic.Play(HapticType.Light);
        }

        private void OnReviewClicked()
        {
            App.Haptic.Play(HapticType.Selection);
            // The OS rate-limits this prompt and never reports the result: do not tie rewards to it.
            App.Review.RequestReview();
        }
    }
}

Ví dụ 2: Điều khiển luồng kết thúc màn chơi với DialogQueue

Kịch bản điều phối kết thúc màn chơi bằng lớp Plain C#: Đẩy các popup thưởng và quà tặng vào DialogQueue theo thứ tự ưu tiên, đăng ký WhenIdle để chuyển scene khi toàn bộ popup đã đóng. Queue thuộc về scene: controller của scene tạo trong Start() và Dispose() trong OnDestroy():

using System;
using TapBrain.Core;
using TapBrain.Core.Services;
using UnityEngine;

namespace MyGame.Gameplay
{
    // Plain C# coordinator. LevelSummaryDialog and LuckyBonusDialog are your own DialogBase
    // subclasses with prefabs under Resources/Dialogs/.
    public sealed class LevelEndCoordinator : IDisposable
    {
        // Build index of your own next-level scene (see File > Build Settings).
        private const int NextLevelSceneIndex = 2;

        private readonly DialogQueue _queue;
        private readonly int _completedLevel;
        private readonly bool _hasBonusReward;

        public LevelEndCoordinator(int completedLevel, bool hasBonusReward)
        {
            _completedLevel = completedLevel;
            _hasBonusReward = hasBonusReward;

            // One queue per scene: the owner creates this object in Start and disposes it in OnDestroy.
            _queue = App.Dialogs.CreateQueue();
        }

        public void Execute()
        {
            App.Haptic.Play(HapticType.Success);

            // 1. Main reward popup (highest priority). 'setup' runs AFTER the dialog's OnOpened().
            _queue.Enqueue<LevelSummaryDialog>(
                priority: 100,
                setup: dialog => dialog.SetLevelScore(_completedLevel, 3),
                id: "level_summary"
            );

            // 2. Lucky bonus popup: canShow is re-checked right before it would open.
            _queue.Enqueue<LuckyBonusDialog>(
                priority: 50,
                canShow: () => _hasBonusReward,
                id: "lucky_bonus"
            );

            // 3. Runs once, after every queued popup has been shown and closed.
            _queue.WhenIdle(() =>
            {
                // onClosed fires exactly once, also when the interstitial is skipped (then synchronously).
                App.Ads.TryShowInterstitial("level_end", onClosed: () =>
                {
                    App.Scenes.Load(NextLevelSceneIndex, fade: true);
                });
            });
        }

        public void Dispose()
        {
            _queue.Dispose(); // the queue also disposes itself when SceneLoading fires
        }
    }

    // The scene owns the coordinator: create in Start, Dispose in OnDestroy.
    public sealed class GameplaySceneController : MonoBehaviour
    {
        private LevelEndCoordinator _levelEnd;

        private void Start()
        {
            _levelEnd = new LevelEndCoordinator(completedLevel: 5, hasBonusReward: true);
        }

        // Call this from your own win-detection code (UnityEvent, button, another controller).
        public void OnLevelWon()
        {
            _levelEnd.Execute();
        }

        private void OnDestroy()
        {
            _levelEnd?.Dispose();
        }
    }
}

11. Các sai lầm thường gặp (So sánh Sai vs Đúng)

// 1. Calling SceneManager directly: no fade, no SceneLoading event
SceneManager.LoadScene(1);

// 2. Looking up and toggling a dialog by hand: bypasses the dialog stack
var dialog = FindObjectOfType<SettingsDialog>();
dialog.gameObject.SetActive(true);

// 3. Raw PlayerPrefs key without a prefix, saved on every write
PlayerPrefs.SetInt("coins", 500);
PlayerPrefs.Save();

// 4. Two popups opened at once, no queue: they stack on top of each other
App.Dialogs.Show<LevelSummaryDialog>();
App.Dialogs.Show<LuckyBonusDialog>();

// 1. App.Scenes: fade, raycast blocking, SceneLoading/SceneLoaded events
//    (HomeSceneIndex = the build index of your own scene)
App.Scenes.Load(HomeSceneIndex, fade: true);

// 2. Open through App.Dialogs (managed stack, one instance per type)
App.Dialogs.Show<SettingsDialog>();

// 3. LocalStorage with your own "game." prefix
LocalStorage.SetInt("game.coins", 500);
// Call LocalStorage.Save() only at checkpoints (CoreHost also saves on Pause/Quit)

// 4. DialogQueue: one popup at a time, by priority
//    Create it in Start(), call _queue.Dispose() in OnDestroy()
_queue = App.Dialogs.CreateQueue();
_queue.Enqueue<LevelSummaryDialog>(priority: 100);
_queue.Enqueue<LuckyBonusDialog>(priority: 50);

12. Checklist kiểm tra nhanh