01 — Vòng lặp cốt lõi (chặt cây → tiền → nâng cấp → stage → mở khoá → Rebirth)

Nguồn framework: docs/framework/07-progression-managers.md §3, docs/framework/05-characters-pets-enemies.md §3.6, docs/framework/09-prestige-rebirth.md §3.1/§3.3, docs/framework/02-combat-projectiles.md §3.1/§3.5, [liveops catalog: UNLOCK_GATES.md] §1–§2. Cấp bằng chứng: L1 ANALYSIS — dựng lại clean-room từ disasm + metadata + quan sát runtime; không phải source gốc. Mỗi dòng bên dưới mang nhãn bằng chứng riêng.

Mục tiêu

Muốn làm một game idle "bắn cây kiếm tiền" thì trước hết phải nhìn thấy toàn bộ vòng lặp trong một trang: người chơi làm gì, số nào tăng, số nào reset, và cửa nào mở ra ở đâu. Trang này vẽ vòng lặp của CatGunner từ viên đạn đầu tiên tới lần Rebirth đầu tiên, kèm đúng hàm (và RVA) thực hiện từng bước — để artist biết mình đang vẽ cho khoảnh khắc nào, và dev biết mình đang copy hành vi nào.

Game gốc làm gì

Vòng lặp nhìn từ trên xuống

   ┌──────────────────────────────────────────────────────────────────────────┐
   │                            VÒNG TRONG (mỗi màn)                          │
   │                                                                          │
   │   Cat bắn ──> Bullet trúng ──> Damage_Collider ──> Enemy.Damaged         │
   │                                     │                    │               │
   │                                     │              Health_Now <= 0       │
   │                                     v                    v               │
   │                       (Ore: -1 mỗi nhát)           Enemy.Die            │
   │                                                          │               │
   │                                    Gamemanager.Get_Money(Money, pos)     │
   │                                                          │               │
   │            Money += MoneyValue_return(v)  (chuỗi nhân Upgrade×Rebirth×…) │
   │                                                          │               │
   │              mua Upgrade Power / Speed / Money  (Upgrade_manager)        │
   │                                                          │               │
   │        Tree.Die_Reload → Tree_Destroyed: TreeCount_Now-- → 0 ⇒ Game_Win │
   │                                                          │               │
   │         StageAdvance: Level_Now 0..4, hết 4 ⇒ Stage_Now++                │
   │         Stage_Value_Max = max(Level_Now + 10·Stage_Now)                  │
   │                                                          │               │
   │         Contents_Lock_Reload: mở Rebirth/Mine/Fish/Boss/Pet/Hunt/Trip    │
   └──────────────────────────────────────────────────────────────────────────┘
                                                              │
                                                              v
   ┌──────────────────────────────────────────────────────────────────────────┐
   │                            VÒNG NGOÀI (Rebirth)                          │
   │   thưởng Ruby = n^2.5 (n = Level_Now + 5·Stage_Now; 0 nếu Stage_Now<=1)   │
   │   RESET: Money, Money_Accum, mọi Upgrade Lv, Stage_Now, Level_Now         │
   │   PERSIST: Ruby, Rebirth_Count, cây prestige, Dia, PetCoin, súng/pet/…    │
   │   Ruby → mua node Damage / Speed / Money (Rebirth_manager) → nhân thu nhập│
   └──────────────────────────────────────────────────────────────────────────┘

Từng bước, kèm hàm thật

Đối chiếu với save thật

Ảnh chụp [device evidence: user_screenshot_stage5-4.png] (sha256 04ef8221…): "Stage 5-4" ⇒ Stage_Now = 4, Level_Now = 3 ⇒ Stage_Value = 43. Theo bảng cổng: Rebirth (20) mở, Mine (30) mở; Fish (50), Boss (90), Pet (110), Hunt (110), Trip (340) khoá — khớp 100 % với ảnh (UNLOCK_GATES §1.5, mức: VERIFIED + observed).

Công thức / pseudocode

// ---- L1 ANALYSIS (có RVA) ----

// Tree_manager.StageAdvance — RVA 0x2B45820
if (Level_Now >= 4) { Level_Now = 0; Stage_Now += 1; } else { Level_Now += 1; }

// Tree_manager.Game_Win — RVA 0x2B452E4 (đoạn tại 0x2B45520..0x2B4557C)
v = Level_Now + 10 * Stage_Now;
if (v >= Stage_Value_Max) {
    Stage_Value_Max = v;               // monotonic
    Rank_manager.SubmitScore(...);     // R1-adjacent (leaderboard)
    Contents_Lock_Reload();
}

// Tree_manager.Contents_Lock_Reload — RVA 0x2B4441C
Rebirth_Btn_Locked_obj.SetActive(Stage_Value_Max < 20);
Mine_Btn_Locked_obj.SetActive(Stage_Value_Max < 30);
Fish_Btn_Locked_obj.SetActive(Stage_Value_Max < 50);
Boss_Btn_Locked_obj.SetActive(Stage_Value_Max < 90);
Pet_Btn_Locked_obj.SetActive(Stage_Value_Max < 110);
Monster_Btn_Locked_obj.SetActive(Stage_Value_Max < 110);
Adventure_Btn_Locked_obj.SetActive(Stage_Value_Max < 340);

// Gamemanager.Get_Money — RVA 0x2A4ECBC / 0x2A4EDD8
v = MoneyValue_return(v); Money += v; Money_Accum += v; OnMoneyChanged?.Invoke();
// (bản có Vector3) + Money_Txt_Spawn(v.InfVal_change(), pos)

// Rebirth_manager.Rebirth — RVA 0x2B22AE0 (tóm tắt theo doc 09 §3.1)
n = Level_Now + 5 * Stage_Now
reward = n^2.5 * Relic_manager.Rebirth_Value / 100      // ToPrecision(5), CẮT
if (Stage_Now <= 1) reward = 0
if (is_UpgradeRebirth) reward *= 3                       // [R1] ad / IAP
Get_Ruby(reward); Rebirth_Count++
Money_Reset(); Upgrade_manager.Reset_Upgrade(); Tree_manager.Rebirth_Reset(); Cat_manager.Balance_Reload()

// ---- Gợi ý framework (không phải code game) ----
interface IGameLoop {
    void OnKill(BigNum drop, Vector3 pos);   // -> Wallet.Earn(Chain(drop)) + text
    void OnWaveCleared();                    // -> StageAdvance + Stage_Value_Max + gates
    void Prestige();                         // -> registry ResetOnPrestige / Persistent
}
// Cổng mở khoá là MỘT số nguyên monotonic + một bảng ngưỡng; đừng tạo cờ bool riêng cho từng feature.

Bẫy đã gặp

• Thiếu guard is_gaming ⇒ kinh tế sai âm thầm. Game chỉ có một scene, quái và đạn luôn tồn tại kể cả khi mở shop. Enemy.Damaged / Enemy.Die từng bị dựng lại thiếu if (!Gamemanager.is_gaming) return; ⇒ quái vẫn ăn damage và rơi tiền trong menu. Đã sửa, ghi G132b (doc 02 §3.5, doc 08 §3.1).
• Stage_Value_Max không reset khi Rebirth — đó là tính năng, không phải bug: nút đã mở thì không khoá lại (UNLOCK_GATES §1.2, RVA 0x2B45534). Nếu bạn "tiện tay" reset nó trong Prestige(), người chơi sẽ mất quyền vào Mine/Fish sau mỗi vòng.
• Rebirth sớm trả 0 Ruby (Stage_Now <= 1) — cổng chống spam rebirth, không phải lỗi tính toán (doc 09 §3.4, RVA 0x2B22F18).
• Bảng cân bằng KHÔNG sinh lúc chạy. Balance_Reload của Upgrade/Rebirth/Gun là DEAD CODE trong 1.1.59 (0 code-xref); bảng thật là mảng serialize trong Main.unity, sinh bằng lặp có cắt v[i] = trunc3(v[i-1]·k), và ToPrecision CẮT — không phải pow(), không phải làm tròn (doc 09 §3.2, [phân tích nội bộ], GAPS G138a). Doc 01 §2 vẫn ghi phiên bản cũ ("làm tròn", "sinh lúc chạy") — coi doc 09 là bản đúng.
• Game_Win gọi Rank_manager.SubmitScore ngay sau khi ghi Stage_Value_Max (RVA 0x2B45574). Bất kỳ probe/cheat nào chỉnh stage rồi để Game_Win chạy sẽ đẩy điểm giả lên leaderboard thật (GAPS G148).
• Cache LRU của MoneyValue_return phải invalidate khi mua upgrade (InvalidateMoneyCache RVA 0x2A4E324), nếu không người chơi trả tiền mà thu nhập không đổi tới khi key bị đẩy khỏi cache (doc 01 §3.3).

Checklist khi tự làm

• [ ] Có một cờ trạng thái toàn cục (is_gaming) được kiểm ở mọi entry-point gây hậu quả kinh tế (Damaged, Die, Get_Money).
• [ ] Bộ đếm wave là một số nguyên (TreeCount_Now), tỉ lệ thanh tiến độ tính lại từ nó, không có state trùng.
• [ ] Stage/level 0-based trong code, +1 chỉ khi hiển thị.
• [ ] Biến cổng mở khoá là một số monotonic (max(Level + 10·Stage)), ngưỡng là hằng số trong code; không reset khi prestige.
• [ ] Thưởng prestige có cổng chống farm sớm (Stage_Now <= 1 ⇒ 0) và siêu tuyến tính theo tiến độ (n^2.5).
• [ ] Prestige() gọi đủ 3 nhóm reset (tiền, upgrade, stage) và không chạm súng/pet/relic/skin — tốt hơn: đăng ký khai báo ResetOnPrestige / Persistent (doc 09 §4.2).
• [ ] Nhiệm vụ chỉ theo dõi hành động cốt lõi (4 loại là đủ cho một game thương mại).
• [ ] Mọi call-site ad/IAP trong vòng lặp (buff ×3, rebirth ×3) đi qua interface fail-closed (R1).

Điều chưa biết (UNKNOWN)

• ~~Công thức máu/tiền theo stage~~ — ĐÃ ĐÓNG (G395): seed 250 (máu) / 20 (tiền), ×3 mỗi stage, cắt về 2 chữ số có nghĩa; mảng scene khớp (250, 750, 2200, 6600, 19000…). Xem 05.
• 2/5 code-xref còn lại tới Contents_Lock_Reload — UNKNOWN (UNLOCK_GATES §2.4).
• Phân rã hệ số ×7.61 theo từng mắt (Upgrade/Rebirth/Skin/Pet/Relic) — UNKNOWN, chỉ đo được tích (doc 01 §6, G142).
• Panel nâng cấp hiển thị giá trị gì qua Value_str_Return (0x2B49134) — CHƯA dựng lại (doc 07 §5); ảnh chụp khớp 4/4 với mảng scene (doc 09 §3.2) nên câu hỏi còn lại là đường sinh chuỗi, không phải con số.
• Kinh tế offline là một mô hình riêng (OfflineProgressSimulator) — đã dựng trọn và khớp game gốc 17 chữ số (G382; 12 luật + ví dụ số thật ở 14); khoản trả trên thiết bị còn chờ 9 stub nhỏ.

Đọc thêm

• ../framework/07-progression-managers.md — bộ khung 35 manager, 4 quy ước method
• ../framework/09-prestige-rebirth.md — vòng ngoài đầy đủ, bảng scene, sim [K]
• ../framework/01-economy-money.md — chuỗi nhân, LRU, notation
• ../framework/02-combat-projectiles.md §3.5 — bug is_gaming
• 14 — Lưu game & offline — điều gì xảy ra giữa hai phiên chơi
• [liveops catalog: UNLOCK_GATES.md] — bảng ngưỡng 7 feature, chuỗi bằng chứng
• [phân tích nội bộ] — hai phân tích độc lập hội tụ về Balance_Reload dead code
• gap list (nội bộ) — G132b, G138a, G142, G143, G148