Chương 1: Giới thiệu về TapBrain Prototype Template

Dành cho bạn mới gia nhập team TapBrain

Tài liệu này được biên soạn đặc biệt cho các bạn lập trình viên Unity/C# đã có khoảng 6 tháng kinh nghiệm (đã nắm cơ bản về C# và MonoBehaviour trong Unity). Đừng lo lắng nếu bạn chưa từng làm việc với Interface, Service Locator, Asmdef, Mediation hay IAP Receipt Validation — hướng dẫn này sẽ dẫn dắt bạn từng bước một qua code thực tế của dự án!

1. Template này là gì và tại sao nó tồn tại?

Trong ngành công nghiệp game mobile, đặc biệt là các thể loại Casual, Puzzle và Hybrid-Casual, tốc độ kiểm chứng thị trường là yếu tố sống còn. Mỗi tháng, team phát triển của TapBrain có thể phải tạo ra 2 đến 4 bản prototype khác nhau để chạy thử nghiệm thu hút người dùng (User Acquisition - UA test).

Nếu mỗi lần làm một game mới, lập trình viên lại phải tích hợp lại từ đầu: Firebase, AppLovin MAX, Unity IAP, GameAnalytics, AppMetrica, popup ATT iOS, hệ thống lưu trữ, hệ thống popup... thì sẽ mất ít nhất từ 1 đến 2 tuần chỉ cho các tác vụ kỹ thuật lặp đi lặp lại. Hơn nữa, việc tích hợp vội vã thường kéo theo vô số lỗi nguy hiểm như: mất receipt khi user mua hàng, treo game khi mất mạng, hay hiển thị quảng cáo liên tục gây ức chế cho người chơi.

TapBrain Prototype Template (xây dựng trên nền tảng Unity 2022.3.62f2 cho Android và iOS IL2CPP) ra đời để giải quyết triệt để vấn đề này. Đây là bộ khung tiêu chuẩn chứa sẵn toàn bộ tầng Core hoàn chỉnh, an toàn và tối ưu nhất, giúp bạn có thể bắt tay vào viết gameplay ngay lập tức chỉ sau 10 phút clone dự án.

2. Bài học xương máu từ dự án cũ (Word Relax)

Trước khi có template này, các game mới thường được copy trực tiếp từ source code của dự án game Word Relax cũ. Điều đó đã tạo ra những "cơn ác mộng" bảo trì:

Spaghetti code & Tight Coupling: Một file FirebaseAnalyticsController.cs phình to hơn 5.500 dòng, chứa cả logic gameplay, tính coin, kiểm tra từ vựng lẫn lệnh gửi analytics.
Lạm dụng Singleton: Khắp nơi đều là GameController.instance, SoundManager.Instance, AdsManager.Instance. Khi chuyển scene hoặc reload, các biến static này không được giải phóng, gây rò rỉ bộ nhớ (memory leak) và lỗi MissingReferenceException triền miên.
Rác dữ liệu và Dependencies thừa thãi: Khi clone sang một game mới hoàn toàn khác thể loại, hàng chục package không dùng tới (như AI Navigation, 2D Animation, SoftMask, Legacy Analytics) và hàng ngàn asset cũ vẫn nằm lại trong project, làm tăng dung lượng build lên thêm hàng chục Megabyte.
Không có chốt chặn kiểm tra: Không ít lần team xuất bản bản test lên Google Play nhưng vẫn để nguyên key test của dự án cũ, dẫn đến việc mất doanh thu quảng cáo hoặc dữ liệu analytics bị gửi nhầm project.

Bài học cốt lõi

Tuyệt đối không để Core biết gì về Game! Tầng Core chỉ đóng vai trò là một thư viện cung cấp dịch vụ hạ tầng. Code Game chỉ được phép gọi Core, Core không bao giờ được phép using TapBrain.Game.

3. Trong template có gì và không có gì?

Những gì CÓ SẴN (Sẵn sàng sử dụng 100%):

Hệ thống / Dịch vụ	Triển khai trong Template	Lợi ích mang lại
Boot Flow tự động	`Bootstrapper` chạy trước scene đầu tiên qua `[RuntimeInitializeOnLoadMethod]`.	Không cần kéo thả bất kỳ prefab "GameMaster" nào vào scene. Bạn có thể bấm Play ở bất kỳ scene nào (Loading, Home, Main) mà không sợ lỗi.
Time-boxed Init Pipeline	`InitPipeline` gồm 10 bước độc lập, mỗi bước có thời gian chờ (timeout) cụ thể.	App không bao giờ bị đơ (freeze). Nếu mất mạng hoặc Firebase lỗi, bước đó sẽ timeout và game vẫn vào được Home bình thường.
AppLovin MAX Ads	`MaxAdsService` hỗ trợ Banner, Interstitial, Rewarded, App Open + cơ chế `AdsPolicy`.	Quản lý khoảng cách giữa các lần hiện quảng cáo (frequency cap), tự tắt tiếng game khi xem quảng cáo, tự động chặn interstitial khi đã mua Remove Ads.
Unity IAP 5.3.1	`IapService` kết hợp với `PendingOrderStore`.	Giao dịch mua hàng chuẩn crash-safe: Nếu game bị tắt đột ngột khi đang mua, đơn hàng được lưu lại và tự động cấp lại ở lần mở app tiếp theo.
Analytics Hub	`AnalyticsService` đa kênh: Firebase + GameAnalytics (ILRD) + AppMetrica.	Gọi hàm log một lần duy nhất qua `App.Analytics.LogEvent()`, sự kiện tự động bắn sang cả 3 hệ thống backend.
Dịch vụ nền tảng di động	iOS ATT (App Tracking Transparency), Apple Search Ads, Local Notifications, In-App Update, In-App Review, Haptics.	Tích hợp sẵn đầy đủ mọi yêu cầu chuẩn chỉ của Apple Store và Google Play Store.
Hạ tầng UI & Tiện ích	`DialogService` (quản lý popup stack), `UIOverlay` (fade màn hình, toast, màn chặn tương tác), `AudioService`, `LocalStorage`.	Giao diện mượt mà, xử lý nút Back trên Android chuẩn xác, lưu trữ dữ liệu an toàn.
Vòng lặp gameplay mẫu	`GameplayController`, `LevelSession`, `MainScreen`, `ResultDialog`.	Có sẵn luồng: Bắt đầu màn chơi → Thắng/Thua → Hiện popup kết quả → Nhận thưởng x2 bằng quảng cáo hoặc qua màn kế tiếp.
Chốt chặn kiểm tra Build	`CoreConfigTools` và Debug Service Panel (phím F1).	Chặn đứng việc build Release nếu cấu hình vẫn còn chứa placeholder `REPLACE_ME` hoặc bundle id mẫu.

Những gì KHÔNG CÓ trong template:

Không có gameplay cụ thể: Chỉ có 2 nút mẫu WIN (test) và LOSE (test) để bạn bấm kiểm tra luồng. Bạn sẽ thay thế 2 nút này bằng gameplay thật của bạn.
Không có hệ thống Online nặng: Không có Server PvP thời gian thực, bảng xếp hạng toàn cầu hay tính năng Bang hội (Clan/Guild).
Không có thuê bao định kỳ (Subscription) hay hệ thống Piggy Bank phức tạp: Đã được dọn dẹp để code nhẹ và dễ hiểu nhất. (Nếu game sau này cần, có thể lấy lại từ commit snapshot lịch sử git).

4. Lộ trình học tập đề xuất (Khung 2 tuần cho người mới)

Để không bị quá tải kiến thức, chúng tôi đề xuất lộ trình làm quen với template trong vòng 2 tuần làm việc:

Tuần 1

Nền tảng & Kiến trúc

Ngày 1Chạy thử Loading → Home → Main. Thử F1 Debug panel
Ngày 2–3Đọc kỹ Chương 2 (Kiến thức C#, Unity, Pattern)
Ngày 4Nắm vững Kiến trúc Core vs Game & Luồng Bootstrapper (Chương 3, 4)
Ngày 5Tìm hiểu CoreConfig.asset và cách dùng GameKeys (Chương 6)

Tuần 2

Dịch vụ & Thực hành code

Ngày 6–7Nghiên cứu kỹ Chương 5 (Ads, IAP, Analytics, UI)
Ngày 8–9Làm trọn vẹn 7 bài tập thực hành ở Chương 8
Ngày 10Thực hành Setup game mới (Chương 7) & Checklist Code Review

Chi tiết từng tuần:

Tuần 1: Hiểu cách template vận hành
- Ngày 1: Mở scene Assets/_Project/Scenes/Loading.unity, bấm Play, xem Console log, mở Debug panel bằng phím F1, thử bấm test quảng cáo và IAP.
- Ngày 2 - 3: Đọc kỹ Chương 2: Kiến thức nền cần học. Nắm vững tại sao template dùng Interface, tại sao không dùng Singleton, và cách tránh rò rỉ event.
- Ngày 4: Đọc Chương 3 (Kiến trúc) và Chương 4 (Boot Flow). Hiểu rõ cơ chế InitPipeline.
- Ngày 5: Tìm hiểu Chương 6 (Cấu hình), xem cấu trúc file CoreConfig.asset và GameKeys.cs.
Tuần 2: Bắt tay vào lập trình
- Ngày 6 - 7: Đọc Chương 5 (Chi tiết từng Service), đặc biệt là cách gọi App.Ads, App.Iap, App.Dialogs và GameApp.Wallet.
- Ngày 8 - 9: Tự tay thực hiện 7 bài tập trong Chương 8: Tutorial thực hành. Bắt đầu từ việc tạo mini-game chạm bia thay cho nút WIN/LOSE.
- Ngày 10: Đọc Chương 7 (Setup game mới) và Chương 10 (Quy tắc & Checklist Code Review) để tự tin tạo Pull Request đầu tiên.

Bài tập khởi động ngay hôm nay

Hãy mở Unity Editor, mở scene Loading.unity và nhấn Play. Quan sát cửa sổ Console để tìm các thẻ log [Boot]. Sau đó nhấn phím F1 để bật panel debug, thử bấm "Show Rewarded" hoặc "Buy com.tapbrain.template.coins_small" và quan sát phản hồi trong Game view!