皮皮GO 是一款模擬 GPS 位置的 Android 應用，配合位置型遊戲（Pokémon GO 等）使用。本節說明從零安裝到可以啟動懸浮窗的完整流程。
取得 app-debug.apk（v0.4.10 約 7.66 MB）。透過 USB 線傳到手機，或用 adb install 從電腦直接推送。
adb install -r -i com.android.vending app-debug.apk-i com.android.vending 把安裝來源偽裝成 Play Store，可繞過 MIUI / HyperOS 的「無法安裝來自此來源的應用程式」限制。
用檔案管理員開啟 APK → 點擊安裝。如果跳「未知來源」警告，到 設定 → 安全性 → 安裝未知 App 給檔案管理員授權。
| 權限 | 路徑 | 用途 |
|---|---|---|
| 定位（精確） | App 首次啟動跳出 → 允許「使用 App 時」 | 讓 Android 接受我們設定的測試位置 |
| 在其他 App 上方顯示 | 設定 → 應用程式 → 皮皮GO → 在其他應用程式上層顯示 | 讓 PodDpad 浮窗能蓋在遊戲上 |
| 模擬位置 App | 設定 → 開發者選項 → 模擬位置應用程式 → 選「皮皮GO」 | 必設！否則 GPS 不會動 |
| 修改系統設定 | 設定 → 應用程式 → 皮皮GO → 修改系統設定 | 鎖屏功能輔助（v0.4.5 之後已不強制要求，但建議給） |
| 通知 | 首次啟動跳出 | 顯示「模擬位置中」前景通知 |
啟動懸浮搖桿後，畫面上會出現一個 304dp 寬橫式深色玻璃面板。這就是 PodDpad（艙式控制器）。下圖是各部件位置與名稱：
| 編號 | 元件 | 說明 |
|---|---|---|
| ⓪ | 拖動區（drag area） | 面板頂端 28dp 整條橫帶都能拖。中央有條 80×5dp 灰色 grip 視覺指示 |
| ① | 4-方向 pad | 96dp 容器內 4 顆 30dp 方向鍵，呈「+」排列 |
| ② | 中央 dot | 角色狀態指示燈：靜止 = 半透明白；移動中 = 亮藍 + 光暈 |
| ③ | 座標 + 動作列 | DMS 兩行；下方兩列： 第一列 ✎ 編輯 ⎘ 貼上 ☆ 收藏 第二列 ⤢ 縮小 🔒 鎖屏 |
| ④ | 檔位 chip | 顯示當前 G1/G2 與速度範圍；tap 切換 |
| ⑤ | 關閉鈕 | 停止懸浮搖桿（亦可從通知列「停止」） |
背景會跳出「皮皮GO 模擬位置中」常駐通知。預設位置為 22°44'21.4"N 120°18'17.3"E（高雄）。
不是按住才走，是點一下就「鎖定」往該方向自動行走，再點一下取消。可同時啟動兩個相鄰方向達到斜行：
| 操作 | 結果 |
|---|---|
| tap ↑ | 該鍵亮藍、中央 dot 變藍、開始往北走 |
| 再 tap ↑ | 取消，回到靜止 |
| tap ↑ + tap → | 同時亮藍，向東北斜行（45°） |
| tap ↑ + tap ↓ | 第二個被忽略（對向不允許） |
| 已有兩個，tap 第三個 | 被忽略（最多兩個） |
| 檔位 | 速度範圍 | 適用情境 |
|---|---|---|
| G1 | 10–15 km/h（步行～慢跑） | 孵蛋、慢慢移動探點 |
| G2 | 16–20 km/h（快跑～自行車） | 長距離移動、跑進度 |
| G3 | 55–60 km/h（機車 / 市區） | 跨區快速移動 |
| G4 | 115–120 km/h（高速公路） | 極速跨城 |
每 3 秒會在範圍內重新抽樣一個速度。tap chip 一下會循環切換：G1 → G2 → G3 → G4 → G1。
25.033889 / 121.564500）
支援格式：
25.033, 121.564geo:lat,lng URI@lat,lng 或 !3d!4d）maps.app.goo.gl 短網址（背景 HTTP redirect 後解析）按住面板頂端拖動區（整條 28dp 高的橫帶）拖動，可把 PodDpad 移到螢幕任何位置。中央的灰色細條只是視覺指示，整條橫帶都吃得到觸控。
把常去的地點存起來，一鍵跳轉。例如：家、花蓮、桃園機場、特定電影院、某遊戲熱點等。
📍 家 25.0339, 121.5645
在收藏清單上 長按任一項 → 直接刪除。會有 Toast 確認「已刪除：XXX」。
收藏存在 Android 內部 SharedPreferences（檔名 pipigo_presets），格式 JSON。重灌 App 會清空，匯出 / 同步功能尚未提供。
遇到緊急要看遊戲畫面、或不想被大面板擋住時，可把 PodDpad 縮成一個小的快速控制條。
tap ⤢ 縮小（動作列第二列左邊）→ 整個面板瞬間切到 96dp 寬的迷你版。
| 按鈕 | 動作 |
|---|---|
| 🔒 鎖屏 全寬大鈕（48dp） | 立刻進入鎖屏（同 PodDpad 上的 [🔒 鎖屏]） |
| ↗ 展開 小鈕（30dp） | 恢復成完整 PodDpad |
邊走邊掛遊戲時，把手機螢幕做成「假關機」狀態，避免口袋誤觸、節省電量，但 GPS 模擬仍繼續推送。
WindowManager.LayoutParams.screenBrightness = 0.01f，不需要 WRITE_SETTINGS 權限）
主畫面有獨立的 「啟動鎖屏模式」 按鈕，會在畫面上放一個 48dp 黑色懸浮鈕（可拖動），點一下進入全黑鎖屏。
Pikmin Bloom 的金盆 / 銀盆 / 電影院特殊盆等高價值盆栽，伺服器會額外檢查位置來源是否為「真實 GPS」。一般飛人會被擋下，因為推出去的位置帶 isFromMockProvider() = true 標記。
這個按鈕做的是「乾坤挪移大法」的半自動化：先把目標位置推進去，然後把模擬位置 provider 拔掉。系統還記得「最後一筆位置」（cached location），但 mock 標記已洗掉。在真實 GPS 重新 lock 之前的 0.5–幾秒空窗內，遊戲拿到的是「目標座標 + 真實旗標」，這時去點特殊盆就會被接受。
| 階段 | 系統內部 | 遊戲拿到的位置 |
|---|---|---|
| (1) 飛到目標 | mock provider 推送中 | 含 isMock=true → 特殊盆拒絕 |
| (2) 倒數結束、拆 mock | mock provider 撤掉，但 cache 仍是目標座標 | 暫時無新位置 |
| (3) 關系統定位 | 所有 location source 停 | — |
| (4) 重開定位 | real GPS 開始 fix（需幾秒）；先回 cached | 目標座標 + isMock=false（因為 mock provider 已不存在） |
| (5) Real GPS lock | 真實位置取代 | 真位置（家），但你已點完盆了 |
v0.5.1 起主畫面會自動偵測 Root / LSPosed 環境，顯示對應徽章：
| 徽章 | 意義 | 拉盆方式 |
|---|---|---|
| ⚪ 一般模式 | 無 root | 必須走 🏆 拉盆助手 |
| 🟡 Root 已偵測 | 有 root 但沒 LSPosed | 仍要走 🏆 拉盆助手；建議裝 LSPosed |
| 🟢 Root + LSPosed ✓ | LSPosed framework 已載入 | 若已啟用 Mock Hide module，可直接拉 |
| 🟢 Root + Mock Hide 生效 ✓ | 實際驗證 mock provider flag 已被 hook 掉 | 直接拉特殊盆，不需要拉盆助手 |
| 檢查 | 正確設定 |
|---|---|
| 開發者選項 → 模擬位置應用程式 | 必須選「皮皮GO」 |
| 定位權限 | 「允許」或「使用 App 時允許」 |
| adb shell appops get com.pipigo.app android:mock_location | 應顯示 MOCK_LOCATION: allow |
logcat 是否有 inject denied / provider is not a test provider | v0.4.4 以前的版本在 Android 14+ 會這樣，請升到 v0.4.10 |
| 遊戲是否有反作弊偵測 | 部分遊戲偵測得到 mock provider，皮皮GO 無法繞過 |
adb install -r -i com.android.vending app-debug.apk| Package | com.pipigo.app |
| 版本 | v0.4.10（versionCode 17） |
| minSdk / targetSdk | 26 / 34 |
| APK 大小 | ≈ 7.66 MB |
| Tick 頻率 | 每 100 ms 推送一次（即使靜止也維持 ping，避免遊戲判斷斷線） |
| G1 速度 | 10–15 km/h 範圍內隨機，每 3 秒重抽（GearRandomizer） |
| G2 速度 | 16–20 km/h 範圍內隨機，每 3 秒重抽 |
| G3 速度 | 55–60 km/h 範圍內隨機（機車 / 市區） |
| G4 速度 | 115–120 km/h 範圍內隨機（高速公路） |
| Provider | LocationManager.GPS_PROVIDER（含 elapsedRealtimeNanos） |
| Provider 設定 | powerUsage=1（Low）/ accuracy=1（Fine），Android 14+ 嚴格驗證範圍 |
| 真實化（v0.5.0+） | 每次推送：accuracy 隨機 5–15m、位置 ±2m jitter、speed / bearing 從當前方向真實計算 |
| 特殊盆突破 | 🏆 拉盆助手：倒數 5 秒後 removeTestProvider，利用 cached location 在 real GPS lock 前的空窗繞過 isFromMockProvider() 檢查 |
| Lifecycle | onCreate 時先 removeTestProvider 再 addTestProvider（避免「gps provider is not a test provider」） |
| 預設座標 | 22.739278, 120.304806（高雄） |
| 顯示格式 | DMS（度°分'秒.s"半球） |
| 輸入格式 | DD（十進位）/ Maps 各種網址 |
| 位移公式 | dlat = -vy·v·dt / 111000dlng = vx·v·dt / (111000·cos(lat)) |
| 儲存層 | SharedPreferences 名稱 pipigo_presets、key list |
| 序列化 | JSON 陣列 [{name, lat, lng}, ...] |
| 同名行為 | 覆寫（移除舊項 + append 新項） |
| UI 展開 | PodDpad 內 preset_panel（非 PopupMenu，避免被 overlay window 擋） |
| 解鎖條件 | 1.5 秒內連按兩下同一個音量鍵（VolumeUp ×2 或 VolumeDown ×2） |
| 螢幕亮度 | 主要：overlay window LayoutParams.screenBrightness = 0.01f（v0.4.5+，免權限）備援： Settings.System.SCREEN_BRIGHTNESS = 0（需 WRITE_SETTINGS） |
| 觸控攔截 | 全螢幕 overlay 吞所有觸控；保留音量鍵 KeyEvent |
| WakeLock | PARTIAL_WAKE_LOCK 維持 CPU；FLAG_KEEP_SCREEN_ON 維持螢幕 |
| 版本 | 主要變更 |
|---|---|
| v0.1 | 初版：osmdroid 地圖 + in-app 搖桿、setTestProviderLocation |
| v0.2 ~ v0.2.3 | 整合鎖屏功能；minSdk 21→26；LocationParser 加 !3d/!4d；主畫面 status 顯示版本 |
| v0.3.0 | 方向鍵 hold → tap-toggle；加 1/2 檔速度按鈕；座標 EditText 可編輯（動態切 NOT_FOCUSABLE） |
| v0.4.0 | 整個浮窗視覺重做為 PodDpad Variation C（304dp 橫式吊艙、玻璃面板、accent 冷光藍）；mock 改 100ms tick；G1/G2 範圍隨機 + 3 秒重抽；座標改 DMS；新增 colors.xml + 8 個 drawable + 10 個單元測試 |
| v0.4.1 | 修拖動失效：加專屬 drag_handle 灰條、ACTION_DOWN 改 return true |
| v0.4.2 | 修浮窗寬度被擠成 100dp：WindowManager.LayoutParams.width 改用明確 dp pixel |
| v0.4.3 | 修 Android 14+ mock provider lifecycle：先 removeTestProvider 再 addTestProvider |
| v0.4.4 | 修 Android 14+ ProviderProperties 驗證：powerUsage / accuracy 改為 1, 1 |
| v0.4.5 | 修鎖屏螢幕沒變暗：overlay window 自帶 screenBrightness = 0.01f；+ 加縮小模式 |
| v0.4.6 | 預設座標改高雄 22.739278, 120.304806 |
| v0.4.7 | 收藏功能：PresetsRepository（SharedPreferences + JSON）；動作列加 [☆ 收藏]；edit_panel 加 NAME + [💾 存收藏]；拖動區擴大為 28dp 高 FrameLayout |
| v0.4.8 | 精簡背景服務，減少電力消耗 |
| v0.4.9 | 修收藏 PopupMenu 被擋：改為 PodDpad 內展開的 preset_panel；縮小模式改兩列（🔒 大鈕 + ↗ 展開）；寬度縮成 96dp |
| v0.4.10 | 修動作列右側被切：5 顆按鈕水平總寬超出區域 → 改成兩列：上 [✎ 編輯][⎘ 貼上][☆ 收藏]、下 [⤢ 縮小][🔒 鎖屏] |
| v0.4.11 | 新增 G3 (~60 km/h) 與 G4 (~120 km/h) 檔位，chip 切換循環 G1→G2→G3→G4→G1 |
| v0.5.0 | 新增 🏆 拉盆助手：半自動化「乾坤挪移大法」繞過特殊盆的 isFromMockProvider() 檢查。+ Mock location 真實化（accuracy 隨機、位置 jitter、speed/bearing 計算） |
| v0.5.1 | 新增 Root 環境偵測：主畫面顯示徽章 ⚪一般 / 🟡Root only / 🟢Root+LSPosed / 🟢Mock Hide 生效；若已 root + LSPosed 並啟用 Mock Location Hide，PIPIGO 推位置會自動繞過 isMock 偵測，可忽略 🏆 拉盆助手 |