Chương 11: Từ Điển Thuật Ngữ & 20 Câu Hỏi Thường Gặp (FAQ)

1. Từ điển 40 thuật ngữ chuyên ngành Game Mobile

A. Lập trình C# & Kiến trúc phần mềm Unity

B. Quảng cáo Mediation & Kiếm tiền (Monetization)

C. In-App Purchase (IAP) & Kinh tế Game

D. Nền tảng Backend, SDKs & Công cụ Build

2. 20 Câu Hỏi Thực Tế Thường Gặp (FAQ)

Q1: Tại sao trong Scene không có GameObject nào chứa hàm Start() hay Awake() để khởi động game?

Trả lời: Template sử dụng tính năng thuộc tính C# mạnh mẽ của Unity: [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)] trên phương thức Bootstrapper.Boot() (đặt tại Assets/_Project/Core/Bootstrap/Bootstrapper.cs). Nhờ đó, Unity tự động kích hoạt hàm khởi động này ngay khi người dùng mở ứng dụng, trước khi bất kỳ Scene nào kịp nạp vào bộ nhớ. Điều này giúp loại bỏ hoàn toàn sự phụ thuộc vào các prefab "GameManager" rải rác trong scene.

Q2: Tôi viết mã nguồn gameplay thật ở đâu và kết nối vào hệ thống như thế nào?

Trả lời: Toàn bộ mã nguồn gameplay đặt trong thư mục Assets/_Project/Game/Gameplay/. Điểm vào chính của bạn là phương thức GameplayController.BeginLevel() (được đánh dấu comment TODO(game)). Khi lượt chơi kết thúc (người chơi ghép xong khối, giải đố xong...), bạn chỉ cần gọi phương thức GameplayController.EndLevel(bool won). Toàn bộ logic cộng thưởng, hiện popup kết quả, hiển thị quảng cáo xen kẽ và video x2 thưởng đều đã được template lắp ráp sẵn.

Q3: Tại sao quảng cáo không hiển thị trong Unity Editor khi tôi nhấn test?

Trả lời: Có 2 trường hợp. (1) maxSdkKey trong CoreConfig còn là REPLACE_ME: MaxAdsService bỏ qua việc khởi tạo MAX (log [Ads] MAX SDK key not set in CoreConfig, ads disabled), nên ShowRewarded trả về RewardedResult.NotReady và TryShowInterstitial bỏ qua nhưng vẫn gọi callback. Đây là trạng thái của template gốc và không phải lỗi. (2) Đã điền SDK key và ad unit thật: trong Editor, AppLovin MAX hiển thị quảng cáo giả (editor mock) để bạn test luồng đóng/nhận thưởng. Quảng cáo thật chỉ xuất hiện trên máy thật. Dùng DebugServicePanel (phím F1) để bấm Show Interstitial/Show Rewarded và xem trạng thái sẵn sàng.

Q4: Tôi có thể cài đặt thêm các plugin từ Unity Asset Store (như Spine, Odin, Feel...) không?

Trả lời: Hoàn toàn được và rất dễ dàng! Thư mục Assets/_Project/Game/ có chủ đích không sử dụng asmdef, nghĩa là nó được biên dịch trực tiếp vào Assembly-CSharp mặc định của Unity. Nhờ vậy, mọi script gameplay của bạn có thể trực tiếp gọi đến bất kỳ plugin nào từ Asset Store mà không bao giờ gặp lỗi thiếu tham chiếu Assembly.

Q5: Làm thế nào để thêm một Scene mới vào dự án một cách an toàn và đúng chuẩn?

Trả lời: Bạn chỉ cần thực hiện đúng 3 bước:

1. Mở file Assets/_Project/Core/Infra/SceneLoader.cs, thêm tên scene mới vào enum SceneId.
2. Mở Assets/_Project/Editor/TemplateSetup.cs, thêm scene đó vào danh sách trong phương thức ApplyBuildSettings().
3. Trên thanh menu Unity, nhấn TapBrain → Setup → Apply Build Settings. Khi cần chuyển sang scene mới từ code, hãy gọi App.Scenes.Load(SceneId.YourNewScene).

Q6: Điều gì xảy ra nếu tôi mở trực tiếp scene Main hoặc Home rồi nhấn Play trong Unity Editor?

Trả lời: Game vẫn khởi động và chạy hoàn toàn bình thường! Nhờ cơ chế BeforeSceneLoad của Bootstrapper, toàn bộ các service cốt lõi (ServiceLocator, Config, Storage) đều được khởi tạo trước khi scene Main hay Home xuất hiện. Bạn không bao giờ bị văng lỗi NullReferenceException do quên chạy từ scene Loading khi đang debug dở một màn chơi.

Q7: Làm sao để thay đổi thời gian giãn cách giữa các lần hiện quảng cáo Interstitial mà không cần build lại game?

Trả lời: Mở Firebase Console → vào mục Remote Config → tìm tham số inter_interval_sec và sửa thành số giây bạn mong muốn (ví dụ 45) → nhấn Publish changes. Remote Config chỉ được fetch một lần ở bước boot (InitPipeline), nên giá trị mới có hiệu lực từ lần mở app tiếp theo của mỗi người chơi có mạng. Sau đó AdsPolicy đọc giá trị này mỗi lần quyết định có hiện interstitial hay không. Người chơi offline vẫn dùng giá trị mặc định trong CoreConfig.remoteConfigDefaults (30 giây).

Q8: Tại sao tôi bấm mua gói IAP trong Unity Editor thì lại hiện popup Buy/Cancel mà không bị trừ tiền thật?

Trả lời: Unity IAP tích hợp chế độ Fake Store riêng cho môi trường Editor để lập trình viên có thể kiểm tra toàn bộ luồng mua hàng và kiểm thử hàm cấp phát quà mà không cần phải thực hiện thanh toán thẻ tín dụng thật. Bạn bấm Buy để giả lập mua thành công hoặc Cancel để giả lập hủy.

Q9: Tại sao tôi đã mua IAP thành công nhưng tài khoản trong game không được cộng coin?

Trả lời: Có 2 nguyên nhân phổ biến nhất: 1) Bạn chưa đăng ký hàm cấp phát (App.Iap.SetGrantHandler) trong GameEntry.cs; hoặc 2) Hàm GrantProduct của bạn chưa có nhánh case khớp với mã Product ID của gói đó và đang trả về false. Hãy mở Assets/_Project/Game/Meta/GameWallet.cs và bổ sung mã Product ID vào lệnh switch-case.

Q10: Game của tôi có chơi offline được hoàn toàn khi mất mạng hoặc bật chế độ máy bay không?

Trả lời: Có, 100% chơi được mượt mà! Hệ thống khởi động InitPipeline quy định mỗi bước boot đều có một giới hạn timeout riêng (Firebase 8s, Remote Config 4s, Ads 6s, IAP 8s...; ATT và Notifications chờ người chơi bấm popup lâu hơn). Khi không có mạng, các bước kết nối server sẽ tự động timeout, ghi nhận log cảnh báo và bỏ qua để vào thẳng scene Home. Game tự nạp bộ tham số offline từ CoreConfig.remoteConfigDefaults và dữ liệu lưu từ LocalStorage.

Q11: Có được phép tạo class Singleton với biến static Instance trong thư mục Game/ không?

Trả lời: Tuyệt đối KHÔNG! Quy tắc R4 của template nghiêm cấm mẫu thiết kế Singleton static Instance. Nếu bạn cần một dịch vụ sống suốt game (như Economy, Quest, Inventory), hãy tạo một class C# thuần thông thường, đăng ký nó vào ServiceLocator trong GameEntry.Init() và thêm một thuộc tính truy cập nhanh trong GameApp.cs.

Q12: Sự khác biệt về vai trò và phạm vi giữa App.X và GameApp.X là gì?

Trả lời:

• App.X (nằm trong namespace TapBrain.Core): Là Facade đại diện cho các dịch vụ hạ tầng nền tảng của template dùng chung cho mọi dự án (như App.Ads, App.Iap, App.Scenes, App.Dialogs).
• GameApp.X (nằm trong namespace TapBrain.Game): Là Facade đại diện cho các dịch vụ nghiệp vụ thuộc riêng logic của game bạn đang phát triển (như GameApp.Wallet, GameApp.Progress).

Q13: Tại sao tôi không thể gọi code của thư mục Game/ từ bên trong thư mục Core/?

Trả lời: Thư mục Core/ được gói trong assembly riêng biệt là TapBrain.Core.asmdef, còn thư mục Game/ nằm ở Assembly-CSharp. Theo quy tắc kiến trúc chuẩn R2, Core là nền tảng dùng chung không được phụ thuộc vào bất kỳ logic đặc thù nào của Game. Nếu Core tham chiếu sang Game, compiler sẽ báo lỗi biên dịch ngay lập tức.

Q14: Khi nào tôi nên lưu dữ liệu bằng LocalStorage và khi nào nên dùng RealtimeDbService?

Trả lời: Sử dụng LocalStorage cho toàn bộ dữ liệu cần truy xuất tức thì ngay trên thiết bị của người chơi (số coin, màn chơi hiện tại, tùy chọn bật/tắt âm thanh). Chỉ sử dụng RealtimeDbService khi bạn cần sao lưu hồ sơ người dùng lên đám mây Firebase hoặc đẩy dữ liệu phân tích BI (Business Intelligence) phục vụ thống kê người dùng.

Q15: Làm sao để tạo một popup (dialog) mới hiển thị trên màn hình với hiệu ứng mở/đóng chuẩn?

Trả lời: 1) Tạo một script mới kế thừa từ DialogBase (ví dụ: public class ShopDialog : DialogBase). 2) Tạo một prefab có cùng tên ShopDialog.prefab đặt trong thư mục Assets/_Project/Resources/Dialogs/, gốc prefab kéo component ShopDialog và gán panel vào biến content. 3) Trong code, mở popup bằng lệnh: App.Dialogs.Show<ShopDialog>().

Q16: Tại sao các menu TapBrain > Setup > Rebuild Scenes lại cực kỳ nguy hiểm nếu đã chỉnh sửa scene?

Trả lời: Các menu này được thiết kế để tự động sinh lại mã nguồn các scene ban đầu của template từ code C#. Khi bạn nhấn chạy, Unity sẽ ghi đè hoàn toàn và xóa sạch mọi đối tượng, hình ảnh, animation bạn đã tự tay kéo thả vào 3 scene Loading, Home và Main mà không có nút Undo phục hồi! Vì vậy mỗi menu đều hiện hộp xác nhận trước khi chạy, còn Apply Template Player Settings cảnh báo thêm một lần nếu bundle id đã khác com.tapbrain.template. Đừng bấm "Overwrite" trên game đã clone.

Q17: Làm sao để tắt một dịch vụ không dùng đến (ví dụ game không có IAP hoặc không dùng AppMetrica)?

Trả lời: Mở file Assets/_Project/Resources/CoreConfig.asset (hoặc vào menu TapBrain → Select Core Config). Tại nhóm Modules, bạn chỉ cần bỏ tích ô tương ứng (ví dụ: bỏ tích enableIap hoặc enableAppMetrica). Bước boot tương ứng trong pipeline sẽ tự động biến thành no-op và bị bỏ qua trong nháy mắt.

Q18: Tại sao Console báo lỗi thiếu DOTween.Modules hoặc GameAnalyticsILRD sau khi cập nhật SDK?

Trả lời: Khi bạn tải bản cập nhật mới của các SDK này từ Package Manager hoặc Asset Store, quá trình import thường xóa mất file .asmdef phụ trợ mà template đã tạo sẵn. Bạn chỉ cần đọc mục 2 trong docs/AGENT_GUIDE.md và tạo lại các file asmdef tương ứng ở đúng đường dẫn thư mục là lỗi sẽ biến mất.

Q19: Làm sao để xử lý nút Back trên thiết bị Android một cách thống nhất trong toàn bộ game?

Trả lời: Template đã xử lý tập trung nút Back thông qua CoreHost (bắt sự kiện Input.GetKeyDown(KeyCode.Escape)). Khi có popup đang mở, DialogService tự động lắng nghe sự kiện này và đóng popup trên cùng của ngăn xếp (Stack). Nếu bạn muốn xử lý riêng cho một màn hình, chỉ cần đăng ký lắng nghe sự kiện ServiceLocator.Get<CoreHost>().BackPressed += OnBack;.

Q20: Tôi muốn thêm một sự kiện phân tích (Analytics Event) mới khi người chơi tương tác thì làm thế nào?

Trả lời: Chỉ cần gọi một dòng lệnh thông qua facade Analytics:

App.Analytics.LogEvent("level_boss_defeated", new Dictionary<string, object>
{
    { "boss_id", "dragon_fire" },
    { "duration_sec", 45 },
    { "hp_remaining", 120 }
});