154 lines
9.9 KiB
Markdown
154 lines
9.9 KiB
Markdown
# 📱 GaCy Android
|
|
|
|
> **Go port in progress:** the local server now launches the SDK and game
|
|
> processes built from GaCy-go. Teleporting uses the game's own map;
|
|
> 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**.
|
|
|
|
[-3DDC84?style=flat&logo=android)](https://developer.android.com/)
|
|
[](https://kotlinlang.org/)
|
|
[](https://developer.android.com/jetpack/compose)
|
|
[](https://developer.android.com/ndk)
|
|
[](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` ก่อนสลับชื่อ เพื่อป้องกันข้อมูลตัวละครหรือเซฟเสียหาย
|