BABA_YAGA/BABA_YAGA_Updater/sections/03_architecture.md

Kiến trúc Kỹ thuật (Technical Architecture)

Hệ thống của BABA_YAGA được thiết kế theo chuẩn Modular Architecture (Kiến trúc Module), tách biệt hoàn toàn giữa logic xử lý vật lý (Kinematics), trạng thái mạng (Net-State) và phản hồi thị giác (Visual Feedbacks). Điều này đảm bảo hiệu năng cao (High Tickrate) ngay cả trong các môi trường mê cung phức tạp.

1. Advanced Kinematic FSM & Camera Dynamics

Hệ thống điều khiển nhân vật cốt lõi được xây dựng trên mô hình Finite State Machine (FSM) phân cấp. Không chỉ xử lý nội suy vật lý mượt mà, hệ thống còn tích hợp trực tiếp với Procedural Camera Dynamics (Head-bob, Dynamic FOV, Tilt) để tạo ra sự cộng hưởng về cảm giác nhập vai, đồng thời duy trì tính đồng bộ tuyệt đối qua lớp mạng (Networking Layer).

(Lưu ý: Sơ đồ trạng thái dưới đây đã được tối ưu hóa cho thuật toán dự đoán phía Client)

stateDiagram-v2
    direction TB

    state "<img src='https://api.iconify.design/lucide/footprints.svg?color=%23FFD700' width='16' style='vertical-align: middle;'> KINEMATIC GROUND" as Ground {
        [*] --> Idle
        
        state Idle {
            I_P: <img src='https://api.iconify.design/lucide/anchor.svg?color=%23E0E0E0' width='16' style='vertical-align: middle;'> Vel < 0.1m/s
            I_C: <img src='https://api.iconify.design/lucide/activity.svg?color=%23E0E0E0' width='16' style='vertical-align: middle;'> Breathing Cam (0.5Hz)
        }

        Idle --> Moving : Input.mag > 0.1
        state Moving {
            M_P: <img src='https://api.iconify.design/lucide/move.svg?color=%23E0E0E0' width='16' style='vertical-align: middle;'> Speed 2-4m/s
            M_C: <img src='https://api.iconify.design/lucide/video.svg?color=%23E0E0E0' width='16' style='vertical-align: middle;'> Head Bob (1.2Hz)
        }

        Moving --> Sneaking : Hold [Sneak]
        state Sneaking {
            Sn_P: <img src='https://api.iconify.design/lucide/volume-x.svg?color=%2300FF55' width='16' style='vertical-align: middle;'> Acoustic Profile -50%
            Sn_C: <img src='https://api.iconify.design/lucide/arrow-down-to-line.svg?color=%23E0E0E0' width='16' style='vertical-align: middle;'> Collider Height ↓
        }

        Moving --> Sprinting : Hold [Sprint]
        Sneaking --> Moving : Release [Sneak]
        
        state Sprinting {
            Sp_P: <img src='https://api.iconify.design/lucide/zap.svg?color=%23FFD700' width='16' style='vertical-align: middle;'> Speed > 6.5m/s
            Sp_C: <img src='https://api.iconify.design/lucide/aperture.svg?color=%2333CCFF' width='16' style='vertical-align: middle;'> Dynamic FOV Warp
        }

        Sprinting --> Moving : Stamina Depleted
    }

    state "<img src='https://api.iconify.design/lucide/feather.svg?color=%2333CCFF' width='16' style='vertical-align: middle;'> AIRBORNE DYNAMICS" as Air {
        state Jump {
            J_P: <img src='https://api.iconify.design/lucide/arrow-up-circle.svg?color=%23E0E0E0' width='16' style='vertical-align: middle;'> AddForce Up
        }
        state Falling {
            F_P: <img src='https://api.iconify.design/lucide/trending-down.svg?color=%23FF3333' width='16' style='vertical-align: middle;'> Gravity x1.5
        }
        state Landing {
            L_P: <img src='https://api.iconify.design/lucide/ruler.svg?color=%23E0E0E0' width='16' style='vertical-align: middle;'> Impact Raycast
        }

        Jump --> Falling : Vel.y < 0
        Falling --> Landing : KCC.IsGrounded == true
    }

    state "<img src='https://api.iconify.design/lucide/crosshair.svg?color=%23FF3333' width='16' style='vertical-align: middle;'> UTILITY / ACTION" as Utility {
        state Dashing {
            D_P: <img src='https://api.iconify.design/lucide/wind.svg?color=%23FFD700' width='16' style='vertical-align: middle;'> Vector Burst (15m/s)
        }
        state Interacting {
            Int_P: <img src='https://api.iconify.design/lucide/lock.svg?color=%23FF3333' width='16' style='vertical-align: middle;'> Root Motion Lock
        }
    }

    state "<img src='https://api.iconify.design/lucide/globe.svg?color=%2333CCFF' width='16' style='vertical-align: middle;'> NET-SYNC LAYER" as Net {
        state "Input Authority (Client)" as IA
        state "State Authority (Server)" as SA
        IA --> SA : Send Input Tick
        SA --> IA : Force Reconcile
    }

    %% Main Transitions
    Ground --> Air : KCC.IsGrounded == false
    Air --> Ground : OnLandEvent.Fire()
    Ground --> Utility : InvokeAbility()
    Utility --> Ground : Action Complete

    %% Sticky Notes for Technical Context
    note left of Ground
        <img src='https://api.iconify.design/lucide/database.svg?color=%23FFD700' width='14' style='vertical-align: middle;'> Sync: KCC Velocity
        <img src='https://api.iconify.design/lucide/layers.svg?color=%23E0E0E0' width='14' style='vertical-align: middle;'> State: Networked Enum
    end note

    note right of Net
        <img src='https://api.iconify.design/lucide/server-cog.svg?color=%2333CCFF' width='14' style='vertical-align: middle;'> Photon Fusion
        <img src='https://api.iconify.design/lucide/shield-check.svg?color=%2300FF55' width='14' style='vertical-align: middle;'> Anti-Cheat Validated
    end note

2. Tactical Environment Scanner & Interaction

Việc tương tác trong một môi trường bị giới hạn hoàn toàn về tầm nhìn đòi hỏi một hệ thống truy vấn không gian (Spatial Querying) cực kỳ chính xác. Chúng tôi từ chối sử dụng cơ chế Raycast điểm đơn thông thường.

Hệ thống lõi: EnvironmentScanner.cs Sử dụng kết hợp Physics.OverlapSphereNonAlloc để tối ưu hóa bộ nhớ (Zero Garbage Collection) và SphereCast để tính toán đường đạn thể tích. Hệ thống tự động phân tích và trích xuất các đối tượng thỏa mãn đa hình Interface IInteractable, đảm bảo người chơi có thể kích hoạt các thiết bị (Cửa, Máy phát điện, Bẫy) một cách mượt mà ngay cả khi chúng hoàn toàn chìm trong bóng tối.

```