# Escape penacony standalone 📱✨
## ppSR Scene & Map Teleporter - Native Android Application

แอปพลิเคชัน Android Standalone สำหรับจัดการและเทเลพอร์ตแผนที่ในเซิร์ฟเวอร์จำลอง **ppSR (Project Star Rail)** บนระบบปฏิบัติการ Android โดยตรง พร้อมระบบสัมผัส (Touch UI) ที่ทันสมัย และระบบอัปเดตอัตโนมัติในตัว (In-App Auto-Updater)

- **ชื่อแอปพลิเคชันเต็ม (Full Name)**: `Escape penacony standalone`
- **ชื่อแอปพลิเคชันที่แสดงบนอุปกรณ์ (Display Name)**: `Escape penacony`
- **Application ID / Package**: `com.catlas.escapepenacony`
- **สถาปัตยกรรม**: Native Android (Kotlin + Jetpack Compose + Material Design 3)

---

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

1. **Native Touch UI (Jetpack Compose & Material Design 3)**
   - อินเทอร์เฟซมืด (Dark Cyberpunk Theme) ดีไซน์พิเศษ
   - รองรับแถบเลือกดวงดาว (Planet Tabs) แบบเลื่อนแนวนอน และระบบค้นหาฉาก/พิกัดแบบเรียลไทม์
2. **ฐานข้อมูลแผนที่ครบถ้วน (Full Data Parity)**
   - ครอบคลุม **8 ดวงดาว 85 ฉาก/แผนที่** จาก `scenes.json`
   - แยกระบบหมวดหมู่ด้วยแท็กสีชัดเจน:
     - ⚔️ **Combat Ready**: ฉากที่รองรับเสาต่อสู้ Calyx ดั้งเดิมในไคลเอนต์ Official
     - 🗺️ **Safe Scenery**: ฉากสำหรับเดินชมวิว เสา Calyx ซ่อนใต้ดินที่ระดับความลึก Y=-999999 ปลอดภัยจากการแครช
     - 🧪 **4.7 Beta Exclusive**: ฉากพิเศษสำหรับไคลเอนต์เบต้า 4.7
3. **ระบบจัดการไฟล์ผ่าน Android Storage Access Framework (SAF)**
   - เลือกระบุไฟล์ `persistent.json` ผ่าน Document Picker รองรับ Android 10, 11, 12, 13, 14, และ 15+
   - กดปุ่ม **Teleport** เพียงครั้งเดียวเพื่ออัปเดตพิกัดลงไฟล์ `persistent.json` ทันที พร้อมระบบสำรองไฟล์อัตโนมัติ
   - มีปุ่ม **Copy JSON** สำหรับคัดลอก JSON พิกัดไปใช้งานต่อได้ทันที
4. **Custom Coordinates Input**
   - ปุ่มลอย (+) สำหรับกรอก Plane ID, X, Y, Z, และ Map Layer ที่กำหนดเองได้อิสระ
5. **In-App Auto-Updater & OTA Hot Sync**
   - **ตรวจจับเวอร์ชันใหม่ผ่าน GitHub Releases API**: เปรียบเทียบ `tag_name` กับเวอร์ชันในเครื่อง ดาวน์โหลด `.apk` และเรียกตัวติดตั้งระบบอัตโนมัติผ่าน `FileProvider`
   - **OTA Map Update**: ปุ่มซิงค์ดาวน์โหลด `scenes.json` ตัวล่าสุดจาก GitHub Raw ได้ทันทีโดยไม่ต้องลง APK ใหม่
6. **รองรับ 3 ภาษา (Trilingual Support)**
   - สลับภาษาระหว่าง **English (EN)**, **ภาษาไทย (TH)**, และ **简体中文 (ZH)** ได้ทันทีผ่านปุ่มบนแถบเมนูด้านบน

---

## 🏗️ โครงสร้างโปรเจกต์ (Project Structure)

```text
Android APK/
├── app/
│   ├── build.gradle.kts
│   ├── proguard-rules.pro
│   └── src/main/
│       ├── AndroidManifest.xml
│       ├── assets/
│       │   └── scenes.json                      # ฐานข้อมูลแผนที่ 8 โลก 85 แมพ
│       ├── java/com/catlas/escapepenacony/
│       │   ├── MainActivity.kt                  # Activity หลักและ SAF Document Picker
│       │   ├── model/
│       │   │   ├── SceneModels.kt               # โมเดลข้อมูล Planet & Scene & Language
│       │   │   └── PersistentConfig.kt          # โครงสร้าง JSON ของ persistent.json
│       │   ├── data/
│       │   │   ├── SceneRepository.kt           # โหลดและบันทึก scenes.json (รองรับ OTA)
│       │   │   ├── StorageManager.kt            # อ่าน/เขียน persistent.json ผ่าน SAF
│       │   │   └── UpdateManager.kt             # GitHub Releases API & APK Self-Updater
│       │   └── ui/
│       │       ├── MainScreen.kt                # หน้าจอหลัก Compose
│       │       ├── Components.kt                # SceneCard, Badges, Dialogs
│       │       └── theme/                       # Color, Theme, Type
│       └── res/
│           ├── values/                          # strings.xml, colors.xml, themes.xml
│           └── xml/file_paths.xml               # FileProvider path สำหรับติดตั้ง APK
├── gradle/
│   ├── libs.versions.toml                       # Version Catalog
│   └── wrapper/                                 # Gradle Wrapper 8.9
├── build.gradle.kts
├── settings.gradle.kts
└── gradlew / gradlew.bat
```

---

## 🛠️ วิธีการเปิดและคอมไพล์โปรเจกต์ (How to Build)

### 1. เปิดผ่าน Android Studio (แนะนำ)
1. เปิดโปรแกรม **Android Studio**
2. เลือก **Open** แล้วชี้ไปที่โฟลเดอร์ `Android APK`
3. รอ Android Studio ซิงค์ Gradle ให้เสร็จสิ้น
4. เลือกเมนู **Build** > **Build Bundle(s) / APK(s)** > **Build APK(s)** หรือกด Run ลงบนโทรศัพท์ Android / Emulator

### 2. คอมไพล์ผ่าน Command Line (CLI)
เปิด Terminal หรือ PowerShell ที่โฟลเดอร์ `Android APK`:

```bash
# คอมไพล์ Debug APK
./gradlew assembleDebug

# คอมไพล์ Release APK
./gradlew assembleRelease
```

ไฟล์ APK ที่สร้างเสร็จจะอยู่ที่:
`app/build/outputs/apk/debug/app-debug.apk`