04 — Âm thanh (Sound)

Nguồn: chưng cất từ restore SOT com.Chodun.CatGunner 1.1.59 (BardCat). Mọi C# ở đây là L1 ANALYSIS, không phải source gốc.

1. Câu hỏi tài liệu này trả lời

Một idle-shooter bắn ~5 phát/giây và có hàng trăm nút bấm. Nếu mỗi sự kiện phát một AudioSource.PlayOneShot thì âm thanh sẽ thành tiếng ồn trắng và CPU audio-mixer sẽ tăng vọt. CatGunner giải quyết bằng một singleton, một enum, hai AudioSource, và ba tầng chống trùng.

2. Stable truths

Danh mục âm thanh đầy đủ (16 clip đã ship)

Không suy ra ánh xạ. 15 giá trị SfxType và 14 clip SFX là một gần trùng khớp, nhưng ánh xạ SfxType → AudioClip nằm trong sfxEntries[] được serialize trong scene và chưa được trích. Đừng gán SfxType.Click → "Click" chỉ vì tên giống nhau.

3. Mô hình hành vi

3.1 Kiến trúc: một cửa, một enum

        bất kỳ hệ thống nào
                |
                v
   Sound_manager.instance.PlaySfx(SfxType id, float? volumeOverride, float pitch = 1)
                |
        +-------+--------+
        |                |
   sfxMap[id]       chống trùng
   (SfxEntry)       - blockSameFrameDuplicate ? lastPlayedFrame[id] == Time.frameCount -> bỏ
                    - blockCooldownDuplicate  ? Time.time - lastPlayedTime[id] < cooldownSeconds -> bỏ
                |
                v
          sfxSource  (MỘT AudioSource duy nhất cho toàn bộ SFX)

Ba quyết định thiết kế đáng học:

(a) Một AudioSource cho tất cả SFX. Không phải một source mỗi âm thanh, không phải pool source. Đây là lựa chọn có đánh đổi rõ ràng: mất khả năng điều khiển từng âm riêng (dừng riêng, 3D riêng), đổi lấy chi phí mixer cố định và không bao giờ hết voice. Với một game 2.5D nhìn từ trên xuống, âm thanh không cần định vị không gian — đây là đánh đổi đúng.

(b) Nullable<float> volumeOverride. null nghĩa là "dùng volume mặc định của SfxEntry". Không phải -1f hay 0f làm giá trị lính canh. Sạch, và không thể nhầm với "im lặng".

(c) pitch có giá trị mặc định 1. Tham số biến tấu cao độ nằm ngay trong API chính, không phải một overload riêng — nên việc thêm biến tấu ngẫu nhiên (Random.Range(0.95f, 1.05f)) cho âm bắn là một thay đổi một dòng ở call-site.

3.2 Hai tầng chống trùng, độc lập

// suy ra từ layout field (dump.cs:590265) — thân method CHƯA dựng lại
[Header("Duplicate Guard")] [SerializeField] bool  blockSameFrameDuplicate;   // @0x38
[Header("Cooldown Guard")]  [SerializeField] bool  blockCooldownDuplicate;    // @0x39
                            [SerializeField] float cooldownSeconds;           // @0x3C
readonly Dictionary<SfxType, int>   lastPlayedFrame;    // @0x48
readonly Dictionary<SfxType, float> lastPlayedTime;     // @0x50

• Cùng frame — chặn kịch bản "10 quái chết cùng lúc, 10 tiếng nổ chồng lên nhau". Đây là loại trùng lặp gây méo tiếng nặng nhất vì các sóng cộng pha hoàn hảo.
• Cooldown — chặn kịch bản "cùng một âm phát 20 lần trong nửa giây". Mềm hơn, giữ nhịp âm thanh.

Cả hai theo từng SfxType, không phải toàn cục. Tiếng bắn bị throttle không được làm im tiếng bấm nút. Và cả hai là cờ inspector — designer âm thanh bật/tắt được mà không cần lập trình viên.

So sánh với FXThrottle (doc 03), vốn throttle theo thời gian + khoảng cách + trần mỗi frame. Âm thanh không cần tiêu chí khoảng cách (game không dùng âm thanh 3D) nhưng cần tiêu chí cùng-frame mà FX không cần. Hai hệ thống, hai bộ tiêu chí phù hợp với từng miền.

3.3 Nhạc nền: hai clip, hai method

public AudioClip BGM_main;        // @0x58
public AudioClip BGM_contents;    // @0x60
public void BGM_Change_Main()      { … }   // RVA 0x2ACFEC4
public void BGM_Change_SpeedRun()  { … }   // RVA 0x2ACFE14
public void ApplyBGMMute(bool mute){ … }   // RVA 0x2ACD5B0

Chỉ hai trạng thái nhạc: "màn chính" và "nội dung phụ / speed-run". Tên field (BGM_contents) và tên method (BGM_Change_SpeedRun) không khớp nhau — dấu hiệu clip BGM_contents phục vụ mọi chế độ phụ, còn speed-run chỉ là cái đầu tiên cần nó.

Method không tham số — trạng thái nhạc là một phần của trạng thái game, không phải thứ call-site tự chọn. Điều này ngăn tình trạng "mỗi màn hình tự đặt nhạc của nó" và tranh chấp lẫn nhau.

ApplyBGMMute tách riêng khỏi mute SFX: người chơi tắt nhạc mà vẫn nghe hiệu ứng là nhu cầu rất phổ biến.

3.4 Nối SFX vào nút — 322 lần, không viết code

// SFX_BtnScript — RVA 0x2ACF6C8 / 0x2ACF774, 322 instance trong scene
public SfxType _sfx = (SfxType)1;                          // mặc định Button
private void Start() { GetComponent<Button>().onClick.AddListener(Sfx); }
private void Sfx()   { Sound_manager.instance.PlaySfx(_sfx, null, 1f); }

Đây là một component 9 dòng xuất hiện 322 lần trong scene. Không có UnityEvent nối tay trong inspector, không có onClick trỏ tới Sound_manager ở 322 chỗ khác nhau (vốn sẽ vỡ khi đổi tên method). Chỉ cần gắn component và chọn một enum.

Mặc định = SfxType.Button nghĩa là trường hợp phổ biến nhất không cần cấu hình gì. Gắn component lên một nút bất kỳ, nó kêu đúng ngay. Chỉ những nút đặc biệt (Purchase, Fail, Win) mới cần đổi enum.

Đây có lẽ là mẫu có tỉ lệ giá-trị/dòng-code cao nhất trong toàn bộ codebase.

3.5 Mute theo ngữ cảnh — Mute_Panel

// Mute_Panel — RVA 0x2AF00DC / 0x2AF0128, 19 instance
private void OnEnable()  { Cat_manager.is_Shoot_Mute = true;  }
private void OnDisable() { Cat_manager.is_Shoot_Mute = false; }

Một component 4 dòng giải quyết một vấn đề UX thật: khi người chơi mở một panel (shop, nhiệm vụ, gacha), con mèo vẫn bắn phía sau, và tiếng bắn át tiếng UI.

Cơ chế đáng chú ý: - Nó không tắt AudioSource. Nó đặt một cờ mà bên phát ra âm thanh (Cat_manager / Cat.Attack) đọc. Nghĩa là âm bắn không bao giờ được gửi tới mixer, thay vì được phát rồi bị chặn. - Nó dùng OnEnable/OnDisable — vòng đời tự nhiên của panel. Không cần ai nhớ gọi mute/unmute, và không thể kẹt ở trạng thái mute nếu panel bị tắt bằng đường khác. - 19 instance = 19 panel khác nhau tự động có hành vi này chỉ bằng cách gắn component.

Điểm yếu cần biết khi tái dùng: đây là một bool toàn cục, không phải bộ đếm. Nếu hai panel có Mute_Panel cùng mở và một cái đóng, cờ sẽ về false dù panel kia vẫn mở. Trong SOT điều này an toàn vì UI là ngăn xếp một-panel-một-lúc, nhưng một framework tổng quát nên dùng counter, không dùng bool.

4. Framework takeaway

1. Một cửa duy nhất: PlaySfx(enum id, float? volumeOverride, float pitch = 1). Enum, không phải string. Nullable<float> cho "dùng mặc định", không dùng giá trị lính canh. pitch nằm trong API chính để biến tấu ngẫu nhiên là một dòng.

2. Chống trùng theo từng id, hai tiêu chí, bật/tắt từ inspector. csharp bool blockSameFrameDuplicate; // chống cộng pha khi nhiều sự kiện cùng frame bool blockCooldownDuplicate; // chống lặp dày float cooldownSeconds; Dictionary<TId, int> lastPlayedFrame; Dictionary<TId, float> lastPlayedTime; Đây là thứ khác biệt giữa "game có âm thanh" và "game nghe được".

3. Một AudioSource cho SFX là mặc định hợp lý cho game mobile 2D/2.5D. Framework nên cho phép nâng cấp lên pool source khi cần âm thanh 3D, nhưng không bắt trả giá đó từ đầu.

4. Trạng thái nhạc nền là method không tham số, thuộc về trạng thái game. BGM_Change_Main() / BGM_Change_X() — không để call-site tự chọn clip.

5. Component nối-SFX-vào-nút với giá trị mặc định đúng. Một component nhỏ + một enum có default hợp lý thay thế hàng trăm lần nối tay trong inspector. Đây là mẫu nên có sẵn trong framework.

6. Mute theo ngữ cảnh bằng cờ mà bên phát đọc, gắn vào OnEnable/OnDisable. Nhưng dùng counter, không dùng bool, để lồng nhau an toàn.

7. Tách mute nhạc khỏi mute SFX.

8. Ngân sách âm thanh nhỏ đến bất ngờ là đủ. Một game thương mại đầy đủ ship với 16 clip (2 nhạc + 14 SFX, tổng ~4 phút âm thanh, định dạng Vorbis). Đừng nhầm số lượng clip với chất lượng cảm giác — cái tạo ra cảm giác là khi nào âm thanh phát và chống trùng, không phải bao nhiêu.

5. Negative evidence & UNKNOWN

6. Raw evidence

• dump.cs:590227 — enum SfxType (15 giá trị)
• dump.cs:590265 — class Sound_manager (field + 8 method + RVA)
• dump.cs:593380 — Cat_manager.is_Shoot_Mute
• [reconstructed: SFX_BtnScript.cs] — nối SFX vào Button (disasm-proven)
• [reconstructed: Mute_Panel.cs] — mute theo ngữ cảnh (disasm-proven)
• [disasm: leaf_SFX_BtnScript.c], leaf_Mute_Panel.c}
• [runtime trace: runtime_ranking.json] — PlaySfx 208×, ApplyBGMMute 3×
• [report: asset_lane.md] §5 — danh mục 16 AudioClip đầy đủ
• [index: scene_census.json] — SFX_BtnScript 322, Mute_Panel 19

7. Đã đóng bởi FEEL lane (2026-09-05) — cập nhật cho §5