# 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](https://developer.android.com/studio)（或裝 command-line 的 Android SDK）
2. 用 Android Studio 開啟 `hoops-android` 資料夾
3. 等 Gradle sync 完（第一次會下載一些東西）
4. **產生 Gradle wrapper**——在專案根目錄跑：
   ```bash
   gradle wrapper --gradle-version 8.7
   ```
   或在 Android Studio 裡點 `File → Sync Project with Gradle Files`，它會自己生成 `gradlew`、`gradlew.bat`、`gradle/wrapper/gradle-wrapper.jar`。

### 建置 debug APK（測試用）

```bash
./gradlew assembleDebug
```

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

### 建置 release APK（要簽章）

先產生 keystore：
```bash
keytool -genkey -v -keystore hoops-release.keystore \
  -alias hoops -keyalg RSA -keysize 2048 -validity 10000
```

建一個 `keystore.properties`（**不要 commit 到 git**）：
```properties
storeFile=../hoops-release.keystore
storePassword=你的密碼
keyAlias=hoops
keyPassword=你的密碼
```

修改 `app/build.gradle.kts`，加上 signing config（看註解的位置）。然後：
```bash
./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](https://gitlab.com/fdroid/fdroiddata)，告訴 F-Droid 怎麼建置你的 app

metadata yml 大致長這樣：
```yaml
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 那邊永遠不需要改。