Hoops — Android

一個籃球小遊戲的 Android 包裝。遊戲本體是純 HTML5 Canvas，這個 app 就是一層全螢幕 WebView 殼。

為什麼這樣做

• 沒有網路權限 — 遊戲完全離線，所有資源都打包在 assets/ 裡。
• 沒有第三方追蹤 — 沒有 Google Play Services、沒有 Analytics、沒有任何網路請求。
• 沒有自定義 Activity 之外的東西 — 整個 app 就一個 MainActivity.kt，七十幾行。
• F-Droid 友好 — 純開源、無 proprietary 依賴、無外部資源。

專案結構

hoops-android/
├── app/
│   ├── build.gradle.kts
│   └── src/main/
│       ├── AndroidManifest.xml
│       ├── java/blog/wiwi/hoops/MainActivity.kt
│       ├── assets/index.html              ← 整個遊戲在這裡
│       └── res/                           ← icon、主題、字串
├── build.gradle.kts
├── settings.gradle.kts
└── gradle.properties

最重要的是 app/src/main/assets/index.html——這是整個遊戲。要改遊戲邏輯，改這個檔案就好，其他 Android 殼層的東西完全不用碰。

怎麼建置

第一次

1. 安裝 Android Studio（或裝 command-line 的 Android SDK）
2. 用 Android Studio 開啟 hoops-android 資料夾
3. 等 Gradle sync 完（第一次會下載一些東西）
4. 產生 Gradle wrapper——在專案根目錄跑：

   gradle wrapper --gradle-version 8.7
   

   或在 Android Studio 裡點 File → Sync Project with Gradle Files，它會自己生成 gradlew、gradlew.bat、gradle/wrapper/gradle-wrapper.jar。

建置 debug APK（測試用）

./gradlew assembleDebug

APK 會在 app/build/outputs/apk/debug/app-debug.apk，可以直接 adb install 到手機。

建置 release APK（要簽章）

先產生 keystore：

keytool -genkey -v -keystore hoops-release.keystore \
  -alias hoops -keyalg RSA -keysize 2048 -validity 10000

建一個 keystore.properties（不要 commit 到 git）：

storeFile=../hoops-release.keystore
storePassword=你的密碼
keyAlias=hoops
keyPassword=你的密碼

修改 app/build.gradle.kts，加上 signing config（看註解的位置）。然後：

./gradlew assembleRelease

怎麼測

在電腦上先測網頁版

直接在瀏覽器打開 app/src/main/assets/index.html——它就是個獨立的 HTML 檔，可以直接跑。 這是改遊戲邏輯時最快的迭代方式。

用 Android emulator 測

1. Android Studio → Device Manager → 建一個 Pixel 5 之類的 emulator
2. 點綠色 ▶ 跑

用實機測

1. 手機開「開發人員選項」→「USB 偵錯」
2. USB 接電腦
3. Android Studio 應該會看到裝置
4. 點 ▶ 跑

上 F-Droid 的注意事項

F-Droid 會自己從你的 git repo 建置 APK，所以：

1. 把整個專案推到公開 git repo（GitHub、Codeberg 都行）
2. 打 git tag 標版本，例如 v1.0.0
3. 送 metadata PR 到 fdroiddata，告訴 F-Droid 怎麼建置你的 app

metadata yml 大致長這樣：

Categories:
  - Games
License: MIT  # 或你選的授權
SourceCode: https://github.com/你/hoops-android
IssueTracker: https://github.com/你/hoops-android/issues

AutoName: Hoops

RepoType: git
Repo: https://github.com/你/hoops-android.git

Builds:
  - versionName: 1.0.0
    versionCode: 1
    commit: v1.0.0
    subdir: app
    gradle:
      - yes

AutoUpdateMode: Version
UpdateCheckMode: Tags
CurrentVersion: 1.0.0
CurrentVersionCode: 1

完整文件：https://f-droid.org/docs/Submitting_to_F-Droid_Quick_Start_Guide/

F-Droid 會檢查的東西

• ❌ 不能依賴 Google Play Services / Firebase
• ❌ 不能有 proprietary 二進位依賴
• ❌ 不能呼叫追蹤服務（Analytics、Crashlytics 等）
• ✅ 純 OSS 依賴
• ✅ 從原始碼可重現建置

這個專案天生就符合所有條件——只用 androidx，沒有任何 proprietary 東西。

常見問題

Q: 為什麼不直接做成 PWA？ A: PWA 也是個好方案，但要上 F-Droid 必須是真正的 Android app。

Q: 改了 index.html 怎麼快速看效果？ A: 雙擊用瀏覽器開那個檔案，直接玩。要看 Android 上的效果再 build。

Q: APK 大概多大？ A: 約 2–4 MB。幾乎全部是 androidx 的 Kotlin 標準庫。assets/index.html 本身不到 30 KB。

Q: 想加新遊戲模式怎麼辦？ A: 改 index.html，重 build。Kotlin 那邊永遠不需要改。