150 lines
15 KiB
Markdown
150 lines
15 KiB
Markdown
# ppSR & Escape Penacony 📱✨
|
|
## Native Android All-in-One Server & Map Teleporter
|
|
|
|
**ppSR & Escape Penacony** เป็นแอปพลิเคชัน Android แบบ All-in-One ที่รวมทั้ง **ตัวรันเซิร์ฟเวอร์จำลอง ppSR (Embedded Python 3.14)**, **ตัวอัปเดตเซิร์ฟเวอร์ตรงจากต้นทาง AFN**, **ระบบวาร์ปแผนที่ 86 ฉาก**, และ **เครื่องมือปรับแต่งเซิร์ฟเวอร์** ไว้ในแอปเดียวจบ **โดยไม่ต้องใช้สิทธิ์ Root, ไม่ต้องใช้ Shizuku และไม่ต้องติดตั้งแอป com.afn.ppSR แยกต่างหาก**
|
|
|
|
- **Application ID / Package**: `com.catlas.escapepenacony`
|
|
- **เวอร์ชันล่าสุด (Current Version)**: `v1.2.0`
|
|
- **สถาปัตยกรรม (Architecture)**: Native Android (Kotlin + Jetpack Compose + Material Design 3 + Embedded Chaquopy Python 3.14)
|
|
- **Target ABI**: `arm64-v8a` (Android 8.0+ / API 26+)
|
|
|
|
---
|
|
|
|
## 🌟 ฟีเจอร์หลัก (Key Features)
|
|
|
|
### 1. 🚀 Embedded Python 3.14 Server Runtime (รันเซิร์ฟเวอร์ในตัวเอง 100%)
|
|
- **ไม่ต้องลงแอป ppSR เพิ่ม:** ฝัง Chaquopy Python 3.14 Native Runtime ในตัวแอป พร้อมไลบรารี CPython `libpython3.14.so` และ `libchaquopy_java.so`
|
|
- **📦 Pre-bundled Python Dependencies (100% Offline):** บรรจุแพ็กเกจ Python ทั้ง 19 ตัว (`requests`, `werkzeug`, `flask`, `marshmallow`, `dataclasses-json`, `protobuf`, `urllib3`, `certifi`, `idna`, `charset-normalizer`, `jinja2`, `click`, `blinker`, ฯลฯ) ฝังไว้ในแอปตั้งแต่ติดตั้ง หมดปัญหา `No module named 'requests'` หรือ `werkzeug` โดยไม่ต้องต่อเน็ตดาวน์โหลด wheel จาก PyPI
|
|
- **Foreground Service:** รันเป็นบริการเบื้องหลังพร้อมแจ้งเตือนสถานะ (`specialUse` Service) ไม่ถูก Android ฆ่าโปรเซสเมื่อสลับไปเปิดแอปเกม
|
|
- **Network Ports:**
|
|
- Dispatch Server (HTTP / Flask): `127.0.0.1:21000`
|
|
- Gameserver Forward (KCP Packet): `127.0.0.1:23301`
|
|
- **Live Terminal Console:** หน้าจอแสดงผล Log การทำงานของเซิร์ฟเวอร์แบบเรียลไทม์ พร้อมปุ่มคัดลอก (Copy) และล้างหน้าจอ (Clear)
|
|
|
|
### 2. 🛠️ เครื่องมือปรับแต่งและปุ่มต่างๆ ของเซิร์ฟเวอร์ (Server Tools)
|
|
- **🔑 Set Password / Key:** มีหน้าต่างกำหนดรหัสผ่านเซิร์ฟเวอร์ (`key`) ใน `persistent.json`
|
|
- **👤 Edit Trailblazer:** ปรับแต่งเพศตัวเอก (หญิง Stelle / ชาย Caelus) และ Path (ทำลายล้าง, อนุรักษ์, ประสาน, ลบล้าง, ปิติสุข) รวมถึง March 7th ได้ทันที
|
|
- **⭐ EX Eidolon (3 EX Rank) Manager:** เปิด/ปิดการทำงานของระบบ 3 EX Eidolon ปลดล็อกสกิลพิเศษสำหรับตัวละครยอดฮิต (JingYuan [1204], DanHeng IL [1213], Acheron [1308]) ได้สะดวกจากหน้าจอมือถือ พร้อมปุ่ม Enable/Disable All
|
|
- **⚡ Send Hotfix (Online / Offline Toggle):** สลับโหมด `send_hotfix` ในคลิกเดียว:
|
|
- *เปิด (True):* สำหรับต่อเน็ตดึง Assets จาก Hoyoverse
|
|
- *ปิด (False):* สำหรับเล่นแบบออฟไลน์ 100% (ช่วยแก้ปัญหาเปิดเกมแล้วจอดำ)
|
|
- **📁 Misc Files Explorer & Editor:** ตัวจัดการไฟล์ในโฟลเดอร์ `misc/` ในตัว สามารถเปิดดูและแก้ไขไฟล์คอนฟิกต่างๆ เช่น `config.json`, `hotfix.json`, `freesr-data.json`, `persistent.json` ได้สดๆ ภายในแอป
|
|
|
|
### 3. 🔄 ระบบอัปเดตคู่ (Dual Update System)
|
|
- **📱 App Updater (อัปเดตตัวแอป APK):**
|
|
- ตรวจสอบเวอร์ชันล่าสุดของแอปผ่าน GitHub Releases อัตโนมัติในพื้นหลังเมื่อเปิดแอป
|
|
- มีปุ่ม **"Check App Update"** พร้อมปุ่มเลือก **Channel Selector** สลับระหว่าง:
|
|
- 🟢 **Latest (Stable):** รับเวอร์ชันเสถียร
|
|
- 🟡 **Pre-release (Beta):** รับเวอร์ชันทดสอบล่วงหน้า
|
|
- ดาวน์โหลดและติดตั้งไฟล์ APK อัปเดตได้ทันทีจากในแอป
|
|
- **⚙️ ppSR Server Core Updater (อัปเดตไฟล์เซิร์ฟเวอร์):**
|
|
- ซิงค์ตรงกับ File Garden (`VERSIONS` & `build.zip`)
|
|
- ตรวจสอบเวอร์ชันที่ติดตั้งเทียบกับเวอร์ชันล่าสุดอย่างแม่นยำ (แสดงสถานะ "You are using the latest version" เมื่อเวอร์ชันตรงกัน)
|
|
- ระบบติดตั้งแบบ Staging ป้องกัน Zip Slip และสำรองไฟล์คอนฟิกผู้ใช้ (`persistent.json`, `config.json`) โดยใช้วิธี **Smart Schema Merge** ไม่เขียนทับบล็อกข้อมูลตัวละคร (`avatar`) ข้อมูลไม่หายและไม่เกิดบั๊ก
|
|
- เมนู **Select Version Archive** เลือกติดตั้งเวอร์ชันเก่าหรือใหม่ย้อนหลังได้อิสระ
|
|
|
|
### 4. 🗺️ ตัวเลือกโลกและวาร์ปแผนที่ (Escape Penacony Teleporter)
|
|
- ครอบคลุม **8 ดวงดาว 86 ฉาก/แผนที่** จาก `scenes.json` (Astral Express, Space Station, Jarilo-VI, Xianzhou Luofu, Penacony, Amphoreus / Planarcadia ฯลฯ)
|
|
- **รองรับแมพ Beta ล่าสุด:** เพิ่มฉาก **Moment of Joy (Planarcadia Beta)** [Plane ID: 20572] พร้อมระบบ Scene Cache Auto-Bust
|
|
- **ระบบค้นหาและฟิลเตอร์:** ค้นหาชื่อฉากหรือ Plane ID และแยกแท็กชัดเจน:
|
|
- ⚔️ **Combat Ready**: มีเสา Calyx สำหรับต่อสู้
|
|
- 🗺️ **Safe Explore**: เสา Calyx ซ่อนที่ความลึก Y=-999999 ปลอดภัยจากการแครช
|
|
- 🧪 **Beta Exclusive**: ฉากพิเศษสำหรับไคลเอนต์เบต้า
|
|
- **Custom Coordinates:** กรอก Plane ID, X, Y, Z และ Map Layer ที่กำหนดเองได้อิสระ
|
|
- **Smart Teleport Flow:** หากเซิร์ฟเวอร์กำลังทำงาน ระบบจะหยุดชั่วคราว $\rightarrow$ เขียนไฟล์ `persistent.json` (UTF-8 No BOM) $\rightarrow$ รีสตาร์ตเซิร์ฟเวอร์ให้ใหม่อัตโนมัติ
|
|
- **รองรับ 3 ภาษา:** สลับระหว่าง **ภาษาไทย (TH)**, **English (EN)**, และ **简体中文 (ZH)** ได้ทันที
|
|
|
|
### 5. 🛡️ ระบบป้องกันการแครชและซ่อมแซมตัวเอง (Self-Healing & Crash Guard)
|
|
- **SafeDict Runtime:** ห่อหุ้ม `Manager.persistent` ด้วย `SafeDict` คืนค่า Fallback Schema มาตรฐานทันทีหากตรวจพบคีย์ขาดหาย ป้องกัน `KeyError: 'avatar'` (Error 1001_1 / 1001_3) ไม่ให้เซิร์ฟเวอร์หลุด
|
|
- **Router Packet Isolation:** ดักจับ Unhandled Exception ใน Handler เพื่อไม่ให้คำขอเดี่ยวของเกมล่ม Thread `read_loop`
|
|
- **Persistent Auto-Healing:** ซ่อมแซมและตรวจสอบความสมบูรณ์ของ `persistent.json` อัตโนมัติทันทีที่เปิดแอป และก่อนเริ่มเซิร์ฟเวอร์
|
|
- **Werkzeug Android Patch:** แก้ปัญหา `importlib.metadata.PackageNotFoundError` บน Android WSGI Dispatch Server
|
|
|
|
---
|
|
|
|
## 🏗️ โครงสร้างโปรเจกต์ (Project Structure)
|
|
|
|
```text
|
|
Escape-penacony-standalone/
|
|
├── app/
|
|
│ ├── build.gradle.kts
|
|
│ ├── libs/
|
|
│ │ └── chaquopy_java.jar # Chaquopy Java API Runtime
|
|
│ └── src/
|
|
│ ├── main/
|
|
│ │ ├── AndroidManifest.xml # Foreground Service & Permissions
|
|
│ │ ├── assets/
|
|
│ │ │ ├── scenes.json # ฐานข้อมูลแผนที่ 8 โลก 85 แมพ
|
|
│ │ │ └── chaquopy/ # Chaquopy stdlib, bootstrap & app.imy
|
|
│ │ ├── jniLibs/arm64-v8a/ # Native libraries (libpython3.14.so ฯลฯ)
|
|
│ │ ├── python/ # Python scripts (run_ppsr.py, loader.py)
|
|
│ │ └── java/com/catlas/escapepenacony/
|
|
│ │ ├── MainActivity.kt # Main Activity & Permission requests
|
|
│ │ ├── service/
|
|
│ │ │ └── ServerService.kt # Foreground Service จัดการ Python lifecycle
|
|
│ │ ├── data/
|
|
│ │ │ ├── PersistentRepository.kt # จัดการ persistent.json & misc files
|
|
│ │ │ ├── UpdateRepository.kt # ดาวน์โหลดและติดตั้ง build.zip จาก AFN
|
|
│ │ │ └── SceneRepository.kt # โหลดและแปลงพิกัดฉากจาก scenes.json
|
|
│ │ ├── model/
|
|
│ │ │ ├── SceneModels.kt # โมเดลข้อมูล Planet & Scene
|
|
│ │ │ └── PersistentConfig.kt # โครงสร้าง Config พิกัด
|
|
│ │ └── ui/
|
|
│ │ ├── MainScreen.kt # Compose UI หน้าจอหลัก 3 แท็บ
|
|
│ │ ├── Components.kt # Reusable UI widgets
|
|
│ │ └── theme/ # Cyberpunk Dark Theme
|
|
│ └── test/java/com/catlas/escapepenacony/
|
|
│ └── UpdateAndSceneTest.kt # Automated Unit Tests
|
|
├── gradle/
|
|
│ └── libs.versions.toml
|
|
├── build.gradle.kts
|
|
└── settings.gradle.kts
|
|
```
|
|
|
|
---
|
|
|
|
## 🛠️ วิธีการบิลด์ (How to Build)
|
|
|
|
### คอมไพล์ผ่าน Command Line:
|
|
```bash
|
|
# ทดสอบ Unit Tests ทั้งหมด
|
|
./gradlew test
|
|
|
|
# สร้างไฟล์ Debug APK
|
|
./gradlew assembleDebug
|
|
|
|
# สร้างไฟล์ Release APK
|
|
./gradlew assembleRelease
|
|
```
|
|
|
|
ไฟล์ APK ที่บิลด์เสร็จแล้วจะอยู่ที่:
|
|
- `app/build/outputs/apk/release/app-release.apk`
|
|
- หรือตัวสำเนาที่ root โฟลเดอร์: `Escape-penacony-standalone-v1.2.0.apk`
|
|
|
|
---
|
|
|
|
## 📜 บันทึกการเปลี่ยนแปลง (Changelog)
|
|
|
|
### v1.2.0 (Build 8)
|
|
- **New Feature - EX Eidolon (3 EX Rank) Manager:** เพิ่ม UI หน้าต่างปรับแต่งและเปิด/ปิดระบบ 3 EX Eidolon สำหรับตัวละครพิเศษ:
|
|
- JingYuan (จิ่งหยวน) [Avatar ID: 1204]
|
|
- DanHeng IL (จ้าวยลจันทรา) [Avatar ID: 1213]
|
|
- Acheron (อาเคอรอน) [Avatar ID: 1308]
|
|
- **SafeDict & Auto-Heal Protection:** อัปเดตโครงสร้าง Default Persistent และ SafeDict ใน Python Runtime รองรับคีย์ `ex_rank` ครบถ้วน หมดกังวลเรื่อง KeyError
|
|
- **UI Quick Tools Refactor:** ปรับปรุงแผงควบคุม Server Tools เป็นรูปแบบ 2x2 Grid (Password, Trailblazer, EX Eidolon, Misc Files)
|
|
- **Smart Update Persistence:** ปรับระบบผสานข้อมูลตอนอัปเดตเซิร์ฟเวอร์ ให้คงการตั้งค่า `ex_rank` ของผู้ใช้ไว้อย่างปลอดภัย
|
|
|
|
### v1.1.4 (Build 7)
|
|
- **Critical Fix:** แก้ปัญหา Error 1001_1 และ 1001_3 (`KeyError: 'avatar'`) ใน `GetBasicInfoCsReq` ที่ทำให้ Thread `read_loop` เซิร์ฟเวอร์ปิดตัวลง
|
|
- **SafeDict Runtime:** ห่อหุ้ม `Manager.persistent` ด้วย `SafeDict` คืนค่า Fallback Schema อัตโนมัติ ป้องกัน `KeyError` สำหรับทุกคีย์ข้อมูลตัวละคร
|
|
- **Router Crash Guard:** ดักจับ Unhandled Exceptions ใน Packet Handler ไม่ให้เซิร์ฟเวอร์หลักล่ม
|
|
- **Auto-Heal Persistent Storage:** ตรวจสอบและซ่อมแซมไฟล์ `persistent.json` อัตโนมัติเมื่อเปิดแอปและก่อนสตาร์ทเซิร์ฟเวอร์
|
|
- **Smart Update Migration:** ผสานคอนฟิกเดิมของผู้ใช้เข้ากับแม่แบบโครงสร้างที่สมบูรณ์ ป้องกันข้อมูลตัวละครสูญหายตอนอัปเดตเซิร์ฟเวอร์
|
|
- **New Beta Scene:** เพิ่มฉาก "Moment of Joy (Planarcadia Beta)" [Plane ID: 20572] พร้อมระบบ Auto Cache-Bust
|
|
- **App Update Channel Selector:** เพิ่มตัวเลือกรับอัปเดตแอปช่องทาง Latest (Stable) หรือ Pre-release (Beta)
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
This tool is for educational, research, and offline testing purposes only. All game data rights belong to their respective creators and owners.
|