Port Android server runtime to GaCy Go

README.md

@@ -1,4 +1,49 @@
-# 📱 GaCy Android (if you have client and this ps is working pls tell me)
+# 📱 GaCy Android
+
+> **Go port in progress:** the local server now launches the SDK and game
+> processes built from GaC-hkrpg-go. Teleporting uses the game's own map;
+> the older ppSR character settings are not yet connected. On 1 November 2026,
+> the user confirmed that an ARM64 debug build could enter the game and teleport
+> using the in-game map on the same phone. On 2 November, the user confirmed
+> that the updated build started the server, entered the game and restarted the
+> server successfully. Other features still need validation.
+
+The Go SDK, shared-data, game-server and KCP package tests have also passed;
+these automated tests do not establish that every gameplay feature works on
+the Android client.
+
+To build the embedded runtime, use Go and Python with a local checkout of
+GaC-hkrpg-go, then build the app:
+
+```powershell
+python tools/package_go_runtime.py <path-to-GaC-hkrpg-go>
+.\gradlew.bat testDebugUnitTest assembleDebug
+```
+
+After a successful debug build, Gradle also copies the APK to the project root
+as `GaCy-Android-<versionName>-debug.apk`. APK files are excluded by `.gitignore`.
+
+The packaging script uses the checkout's current source and resources and
+seeds player data from its committed defaults. Runtime saves are stored under
+the app's `files/gacy-go` directory; the previous ppSR data remains separate.
+When runtime data is updated, new entries from bundled `hotfix.json` and
+`versions.json` are added without replacing entries already on the device.
+If a previous failed lookup left an entirely empty cached entry, the SDK uses
+available bundled metadata for that version instead of the empty entry.
+Set the Host in Settings to the address the game client should use to reach
+the phone (use `127.0.0.1` when both run on the same device). The Go servers
+use the configured SDK and game ports. Redirecting the game client's dispatch
+traffic is still a separate setup step.
+
+Network settings take effect after restarting the server. Remote mode checks
+the SDK health endpoint periodically and reports an error after three
+consecutive failed checks.
+The connection test clears its previous result when the host, ports or mode
+change, and tests the values currently entered in Settings.
+
+For an x86_64 Android emulator only, add `--emulator` to the packaging
+command and `-PgacyEmulator` to the Gradle command. This adds Linux x86_64
+test executables to the debug APK; ordinary builds contain Android ARM64 only.
 
 <div align="center">
 
@@ -22,24 +67,17 @@ Built with **Kotlin**, **Jetpack Compose**, and **Material Design 3**.
 ### ✨ ฟีเจอร์หลัก (Key Features)
 
 * **🎮 ระบบจัดการเซิร์ฟเวอร์แบบ Dual-Mode (Local & Remote Server Management):**
-  * **โหมด Local Embedded:** รันเซิร์ฟเวอร์จำลองภายในอุปกรณ์ Android โดยตรงผ่าน Android Foreground Service (`specialUse`) ไม่ถูกระบบฆ่าขณะสลับไปเล่นเกม
+  * **โหมด 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% ไม่สร้างความเสียหายแก่ข้อมูลตัวละคร
+* **🗺️ วาร์ปในเกม:** ใช้แผนที่ของเกมผ่าน Game server ของ GaCy Go โดยตรง
 * **⚡ คอนโซลคำสั่ง GM บนมือถือ & เชื่อมต่อ GaCy SRTool:**
-  * **Emergency Unstuck:** ปุ่มปลดบล็อกตัวละครเร่งด่วนผ่าน Heartbeat API (`/api/client/unstuck`) กู้คืนอาการเกมค้าง
-  * **Mobile GM Command Prompt:** พิมพ์และส่งคำสั่ง GM (`/give`, `/avatar`, `/faketime`) ตรงไปยังเซิร์ฟเวอร์ พร้อมปุ่มคีย์ลัดคำสั่งยอดฮิต
+  * **Emergency Unstuck:** ส่งคำขอกู้คืน UI ผ่าน Heartbeat API (`/api/client/unstuck`) แอปแสดงว่าเข้าคิวเมื่อเซิร์ฟเวอร์ตอบกลับพร้อมรหัสคำขอเท่านั้น; การเข้าคิวไม่ได้ยืนยันว่าเกมประมวลผลสำเร็จ
+  * **Mobile GM Command Prompt:** พิมพ์และส่งคำสั่ง GM ไปยังเซิร์ฟเวอร์; ความพร้อมใช้งานขึ้นกับ Go runtime โดย `/give` และ `/heal` ยังไม่รองรับ
+  * **`/max`:** ตั้งตัวละครทั้งหมดเป็นเลเวล 80, ขั้นเลื่อน 6 และแรงก์ 6 โดยแก้เฉพาะข้อมูลตัวละครที่เกี่ยวข้องและเก็บฟิลด์อื่นไว้ ต้องเชื่อมต่อเกมใหม่เพื่อโหลดค่า การทดสอบอัตโนมัติผ่านแล้ว แต่ยังไม่ได้ยืนยันคำสั่งนี้ในเกมจริง
+  * **`/teleport <plane_id> [floor_id]`:** บันทึกค่าฉากลง persistent โดยไม่เขียนไฟล์นำเข้าตัวละครทับ ต้องเชื่อมต่อเกมใหม่ และไม่แทนการวาร์ปผ่านแผนที่ในเกม; ผ่านการทดสอบอัตโนมัติ แต่ยังไม่ได้ยืนยันคำสั่งนี้ในเกมจริง คำสั่ง `/clear lineup` ถูกปฏิเสธเพราะทีมที่ใช้อยู่ต้องไม่ว่าง
   * **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% แก้ปัญหาหน้าจอดำ
+* **⚙️ การตั้งค่า:** ตั้งค่าการเชื่อมต่อและภาษาของแอป; การตั้งค่าตัวละครจาก ppSR รุ่นเก่ายังไม่ได้เชื่อมกับ Go runtime
 * **🎨 หน้าต่าง Cyberpunk Dark สวยงาม ลื่นไหล:**
   * ออกแบบด้วย **Material Design 3** สีสันเข้าชุดกับ G-Launcher Desktop และ GaCy-GO
   * รองรับ 3 ภาษาภายในตัว: **ภาษาไทย (TH)**, **English (EN)**, และ **简体中文 (ZH)**
@@ -53,11 +91,9 @@ 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
@@ -70,27 +106,22 @@ graph TD
     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]
+        PersistentData[Go runtime saves and resources]
         SRToolWeb[GaCy SRTool Web Application]
         StarRailClient[Star Rail Game Client Android]
     end
 
-    ServerTab --> PersistRepo
     ServerTab --> ServerFGS
-    TeleportTab --> SceneRepo
-    TeleportTab --> PersistRepo
+    ServerFGS --> PersistentData
     SRToolTab --> ApiRepo
     SettingsTab --> PrefsRepo
 
-    PersistRepo --> PersistentData
     ApiRepo --> GameServer
     SRToolTab -.-> SRToolWeb
     StarRailClient -.-> GameServer