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)

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:

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

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

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