GaCyGO-Android/README.md

📱 GaCy Android

Modern, High-Performance Mobile Companion & Server Manager for the GaCy Ecosystem
Built with Kotlin, Jetpack Compose, and Material Design 3.

English | ภาษาไทย

---

🇹🇭 ภาษาไทย

✨ ฟีเจอร์หลัก (Key Features)

• 🎮 ระบบจัดการเซิร์ฟเวอร์แบบ Dual-Mode (Local & Remote Server Management):
  • โหมด Local Embedded: รันเซิร์ฟเวอร์จำลองภายในอุปกรณ์ Android โดยตรงผ่าน Android Foreground Service (specialUse) ไม่ถูกระบบฆ่าขณะสลับไปเล่นเกม
  • โหมด Remote Host: เชื่อมต่อและควบคุมเซิร์ฟเวอร์ GaCy-GO บน PC ผ่าน Wi-Fi/LAN พร้อมระบบทดสอบค่าความหน่วง (Ping Latency Test)
  • Live Terminal Console: หน้าต่างแสดงผล Log การทำงานของเซิร์ฟเวอร์แบบ Real-time พร้อมปุ่มคัดลอก (Copy) และล้างหน้าจอ (Clear)
• 🗺️ ระบบวาร์ปแผนที่ 8 โลก 86 ฉาก (Escape Penacony Teleport Engine):
  • ครอบคลุม 8 ดวงดาว 86+ ฉาก จากฐานข้อมูล scenes.json (Astral Express, Herta Space Station, Jarilo-VI, Xianzhou Luofu, Penacony, และแมพเบต้าล่าสุดอย่าง Amphoreus / Planarcadia Beta 20572)
  • ระบบตัวกรองอัจฉริยะ: ⚔️ Combat Ready (มีเสา Calyx สำหรับต่อสู้), 🗺️ Safe Explore (เดินเล่นปลอดภัย), 🧪 Beta Exclusive (ฉากพิเศษสำหรับเบต้า)
  • ค้นหาฉากได้รวดเร็วทั้งภาษาไทย ภาษาอังกฤษ ภาษาจีน หรือกรอก Plane ID
  • Custom Coordinates Teleport: กรอกพิกัด Plane ID, X, Y, Z, Map Layer เองได้อิสระ
  • ระบบบันทึกไฟล์คอนฟิก persistent.json แบบ Atomic Operation ปลอดภัย 100% ไม่สร้างความเสียหายแก่ข้อมูลตัวละคร
• ⚡ คอนโซลคำสั่ง GM บนมือถือ & เชื่อมต่อ GaCy SRTool:
  • Emergency Unstuck: ปุ่มปลดบล็อกตัวละครเร่งด่วนผ่าน Heartbeat API (/api/client/unstuck) กู้คืนอาการเกมค้าง
  • Mobile GM Command Prompt: พิมพ์และส่งคำสั่ง GM (/give, /avatar, /faketime) ตรงไปยังเซิร์ฟเวอร์ พร้อมปุ่มคีย์ลัดคำสั่งยอดฮิต
  • GaCy SRTool Web Integration: ปุ่มลัดเปิดหน้าจัดการกระเป๋า ตัวละคร และสร้าง Relic ผ่าน GaCy SRTool Web
• 🛠️ เครื่องมือปรับแต่งตัวละครและเซิร์ฟเวอร์ (Character & Server Configurator):
  • 🔑 Server Key / Password: ตั้งรหัสผ่านเซิร์ฟเวอร์เพื่อความปลอดภัย
  • 👤 Trailblazer Configurator: สลับเพศผู้บุกเบิก (Stelle หญิง / Caelus ชาย) และเลือก Path (ทำลายล้าง, อนุรักษ์, ประสาน, ลบล้าง, ปิติสุข) ได้ทันที
  • ⭐ 3 EX Eidolon (Rank) Manager: สลับเปิด/ปิดสกิลพิเศษ 3 EX สำหรับตัวละครยอดนิยม (JingYuan [1204], DanHeng IL [1213], Acheron [1308])
  • ⚡ Send Hotfix (Online/Offline Toggle): เปิดสำหรับดาวน์โหลด Assets ออนไลน์จาก Hoyoverse หรือปิดเพื่อเล่นแบบออฟไลน์ 100% แก้ปัญหาหน้าจอดำ
• 🎨 หน้าต่าง Cyberpunk Dark สวยงาม ลื่นไหล:
  • ออกแบบด้วย Material Design 3 สีสันเข้าชุดกับ G-Launcher Desktop และ GaCy-GO
  • รองรับ 3 ภาษาภายในตัว: ภาษาไทย (TH), English (EN), และ 简体中文 (ZH)

---

🏗️ สถาปัตยกรรมระบบ (Architecture)

graph TD
    subgraph AppLayer [UI Layer: Jetpack Compose]
        MainUI[MainScreen & Navigation]
        ServerTab[ServerScreen & Live Terminal]
        TeleportTab[TeleportScreen & 86 Scenes]
        SRToolTab[SRToolScreen & GM Console]
        SettingsTab[SettingsScreen & Network Config]
        MainUI --> ServerTab
        MainUI --> TeleportTab
        MainUI --> SRToolTab
        MainUI --> SettingsTab
    end

    subgraph ServiceLayer [Background Services]
        ServerFGS[ServerService - Foreground Service]
        LogStream[LogBuffer - Circular StateFlow]
        ServerFGS --> LogStream
        LogStream --> ServerTab
    end

    subgraph DataRepositories [Data & Repository Layer]
        SceneRepo[SceneRepository - scenes.json Cache]
        PersistRepo[PersistentRepository - persistent.json]
        ApiRepo[GaCyApiRepository - OkHttp Client]
        PrefsRepo[PreferencesRepository - SharedPreferences]
    end

    subgraph GameEcosystem [GaCy Ecosystem & Storage]
        GameServer[GaCy-GO Server / Remote PC]
        PersistentData[persistent.json / misc Configs]
        SRToolWeb[GaCy SRTool Web Application]
        StarRailClient[Star Rail Game Client Android]
    end

    ServerTab --> PersistRepo
    ServerTab --> ServerFGS
    TeleportTab --> SceneRepo
    TeleportTab --> PersistRepo
    SRToolTab --> ApiRepo
    SettingsTab --> PrefsRepo

    PersistRepo --> PersistentData
    ApiRepo --> GameServer
    SRToolTab -.-> SRToolWeb
    StarRailClient -.-> GameServer

---

🚀 วิธีการคอมไพล์และเปิดโปรเจกต์ (Build & Run)

ความต้องการของระบบ (Requirements)

• Android Studio (Ladybug / Koala หรือใหม่กว่า)
• Java Development Kit (JDK): JDK 17 หรือ 21
• Android SDK: Compile SDK 35 (Android 15), Min SDK 26 (Android 8.0)

1. เปิดด้วย Android Studio

1. เปิดโปรแกรม Android Studio
2. เลือก Open แล้วนำทางไปยังโฟลเดอร์ GaCy Android
3. รอระบบ Gradle ซิงค์ไลบรารีทั้งหมดให้เสร็จสิ้น

2. คอมไพล์ผ่าน Command Line

# คอมไพล์ไฟล์ APK โหมด Debug
.\gradlew.bat assembleDebug

# ไฟล์ APK จะถูกสร้างไว้ที่:
# app/build/outputs/apk/debug/app-debug.apk

---

📜 กฎของโปรเจกต์ (Repository Rules)

• ห้าม Hardcode ค่าเฉพาะเครื่อง: ค่า IP, Port, และการตั้งค่าต่างๆ ต้องอ่านและบันทึกผ่าน PreferencesRepository หรือ PersistentRepository
• ระบบจัดการไฟล์แบบ Atomic: การแก้ไขไฟล์ persistent.json ต้องเขียนลงไฟล์ .tmp ก่อนสลับชื่อ เพื่อป้องกันข้อมูลตัวละครหรือเซฟเสียหาย