151 lines
4.5 KiB
Markdown
151 lines
4.5 KiB
Markdown
# 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 那邊永遠不需要改。
|