feat: initialize GaCy Android project foundation (Kotlin, Jetpack Compose, Material 3)

README.md

@@ -0,0 +1,126 @@
+# 📱 GaCy Android
+
+<div align="center">
+
+**Modern, High-Performance Mobile Companion & Server Manager for the GaCy Ecosystem**  
+Built with **Kotlin**, **Jetpack Compose**, and **Material Design 3**.
+
+[![Platform](https://img.shields.io/badge/Platform-Android_8.0%2B_(API_26%2B)-3DDC84?style=flat&logo=android)](https://developer.android.com/)
+[![Kotlin](https://img.shields.io/badge/Kotlin-2.0.21-7F52FF?style=flat&logo=kotlin)](https://kotlinlang.org/)
+[![Compose](https://img.shields.io/badge/Jetpack_Compose-Material_3-4285F4?style=flat&logo=jetpackcompose)](https://developer.android.com/jetpack/compose)
+[![Target ABI](https://img.shields.io/badge/ABI-arm64--v8a-blue?style=flat)](https://developer.android.com/ndk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[English](#-english) | [ภาษาไทย](#-ภาษาไทย)
+
+</div>
+
+---
+
+## 🇹🇭 ภาษาไทย
+
+### ✨ ฟีเจอร์หลัก (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](https://gacy-srtool.vercel.app/)
+* **🛠️ เครื่องมือปรับแต่งตัวละครและเซิร์ฟเวอร์ (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)
+
+```mermaid
+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
+```powershell
+# คอมไพล์ไฟล์ 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` ก่อนสลับชื่อ เพื่อป้องกันข้อมูลตัวละครหรือเซฟเสียหาย