GaCyGO-Android/README.md

# 📱 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">

**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](./Docs/README_EN.md) | [简体中文](./Docs/README_ZH.md)

</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)
* **🗺️ วาร์ปในเกม:** ใช้แผนที่ของเกมผ่าน Game server ของ GaCy Go โดยตรง
* **⚡ คอนโซลคำสั่ง GM บนมือถือ & เชื่อมต่อ GaCy SRTool:**
  * **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/)
* **⚙️ การตั้งค่า:** ตั้งค่าการเชื่อมต่อและภาษาของแอป; การตั้งค่าตัวละครจาก ppSR รุ่นเก่ายังไม่ได้เชื่อมกับ Go runtime
* **🎨 หน้าต่าง 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]
        SRToolTab[SRToolScreen & GM Console]
        SettingsTab[SettingsScreen & Network Config]
        MainUI --> ServerTab
        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]
        ApiRepo[GaCyApiRepository - OkHttp Client]
        PrefsRepo[PreferencesRepository - SharedPreferences]
    end

    subgraph GameEcosystem [GaCy Ecosystem & Storage]
        GameServer[GaCy-GO Server / Remote PC]
        PersistentData[Go runtime saves and resources]
        SRToolWeb[GaCy SRTool Web Application]
        StarRailClient[Star Rail Game Client Android]
    end

    ServerTab --> ServerFGS
    ServerFGS --> PersistentData
    SRToolTab --> ApiRepo
    SettingsTab --> PrefsRepo

    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` ก่อนสลับชื่อ เพื่อป้องกันข้อมูลตัวละครหรือเซฟเสียหาย