204 lines
8.6 KiB
Markdown
204 lines
8.6 KiB
Markdown
# 猫爪游乐场 · Paw Play
|
||
|
||
给猫猫玩的 Android 触摸玩具。不是让猫盯着看的视频，而是会对爪子有回应的三个小游戏。
|
||
|
||
> 在线仓库：<https://git.k1412.top/wuyang/pawplay>
|
||
> 下载 APK：<https://git.k1412.top/wuyang/pawplay/releases>
|
||
> 开源协议：MIT
|
||
|
||
本项目已在 **小米 M367FC / Android 17（API 37）/ 2272×3408** 上实机验证，没有使用模拟器。
|
||
桌面图标叫 **「猫爪游乐场」**，包名 `com.local.pawplay`，当前版本 **1.0.1**。
|
||
|
||
|
||
|
||
## 三个模式
|
||
|
||
| 鱼池 | 红点 | 羽毛 |
|
||
| --- | --- | --- |
|
||
| 6–7 条锦鲤在水里游动、悬停、突然加速。爪子碰到鱼会变成气泡和星星，鱼过一会儿从边缘游回来。 | 经典红点。会停、会突然窜出去；爪子拍到它时整颗点会瞬移，并留下红色余晖。 | 三根暖色羽毛在阳光里慢慢飘。挥爪会带起风，羽毛被吹开、旋转，再慢慢落回来。 |
|
||
|  |  |  |
|
||
|
||
横屏是更舒服的玩法，竖屏也完整支持。全屏、无状态栏、无导航栏，屏幕常亮。
|
||
|
||
## 为什么这样设计（给猫，而不是给人）
|
||
|
||
- **猎物质感**：慢速游动 + 突然加速/停顿 + 方向变化，接近猫会追的小动物。
|
||
- **大目标**：鱼和羽毛都做得够大，猫不需要精确点中。
|
||
- **全屏任意触摸都有反馈**：不是只有“点中按钮”才算。多指、整只爪子拍下来都有水波、气泡或风。
|
||
- **没有失败**：没有分数、倒计时、Game Over、广告、内购、弹窗、联网。
|
||
- **不闪屏**：动画平滑，没有高频闪烁；对猫的视觉更友好。
|
||
- **声音柔和**：四段很短的轻音效，默认开启，可以一键关掉。不会突然爆音。
|
||
- **家长入口藏起来**：要长按角落的爪印 2 秒才会打开，猫乱拍不会误触。
|
||
- **不收集数据**：APK 没有申请任何权限，也没有 INTERNET 权限。
|
||
- **60fps**：单 Activity + 自绘 View + Choreographer，实测 1191 帧里 1 帧 janky（0.08%）。
|
||
|
||
## 下载与安装
|
||
|
||
- Release 里提供已签名的 APK（v1.0.1，约 209 KB）
|
||
- 也可以自己从源码构建，见下文
|
||
- 安装后桌面图标为 **「猫爪游乐场」**，首次打开默认进入 **鱼池**
|
||
|
||
## 打开与玩法
|
||
|
||
1. 在桌面点 **「猫爪游乐场」** 图标。
|
||
2. 把平板平放或放在稳定的支架上，让猫猫用爪子直接碰屏幕。
|
||
3. 底部提示条会在约 6 秒后自动消失，不挡游戏。
|
||
4. 鱼池、红点、羽毛在 **家长设置** 里切换。
|
||
|
||
### 家长设置
|
||
|
||
**长按左上角或右上角的爪印 2 秒**（按住不要移动），会出现家长面板：
|
||
|
||
- 切换 **鱼池 / 红点 / 羽毛**（点一下立即生效，面板不会关，方便继续调）
|
||
- **轻柔音效** 开关
|
||
- **继续玩**：关闭面板
|
||
- **退出游戏**：退出并移除任务
|
||
|
||
面板打开时按返回键 = 关闭面板；在游戏界面按一次返回键会提示“再按一次返回键可退出”，2 秒内再按一次才退出。这样猫踩到返回手势不会马上退出。
|
||
如果猫总是从底部手势退出，可以在系统设置里开启 **屏幕固定**（不同系统叫“应用固定/屏幕钉住”），把游戏固定住；退出时再按系统手势解锁。
|
||
|
||
## 猫安全与陪玩建议
|
||
|
||
这不是“把猫交给平板”的产品，建议人陪着玩：
|
||
|
||
- **贴钢化膜**：猫爪和屏幕都需要保护，软膜容易被抓花。
|
||
- **放平/支架**：平板不要放在桌边，避免拍下去；远离水杯。
|
||
- **一次 5–10 分钟**：猫出现甩尾、耳朵后压、瞳孔放大、哈气、躲开，就立刻停。
|
||
- **不要强迫**：有的猫对屏幕完全没兴趣，这很正常；换成红点或羽毛试试。
|
||
- **亮度适中**：晚上不要把亮度拉满；不要在黑暗中长时间玩。
|
||
- **注意卫生**：玩完擦一下屏幕；别让猫咬平板边角或充电线。
|
||
- **屏幕不是猫抓板**：如果猫开始用爪子刨屏幕边缘，停下来，换实体逗猫棒。
|
||
- **不是托管工具**：屏幕互动不能替代真实的追逐、扑咬和陪伴。
|
||
|
||
## 安装信息
|
||
|
||
- 应用名：猫爪游乐场
|
||
- 包名：`com.local.pawplay`
|
||
- 版本：1.0.1（versionCode 2）
|
||
- minSdk 26 / targetSdk 35
|
||
- 大小：约 209 KB
|
||
- 权限：**无**
|
||
- 签名：本机自签名（不是应用商店版本）
|
||
- APK：从 <https://git.k1412.top/wuyang/pawplay/releases> 下载
|
||
|
||
安装：
|
||
|
||
```bash
|
||
adb install -r 猫爪游乐场-1.0.1.apk
|
||
```
|
||
|
||
也可以用系统包管理器安装（例如在设备本机的 shell 中）：
|
||
|
||
```bash
|
||
pm install -r --user 0 /data/local/tmp/猫爪游乐场-1.0.1.apk
|
||
```
|
||
|
||
启动：
|
||
|
||
```bash
|
||
am start -n com.local.pawplay/.MainActivity
|
||
```
|
||
|
||
## 源码与构建
|
||
|
||
```
|
||
app/
|
||
AndroidManifest.xml
|
||
build.sh # 不用 Gradle 的构建脚本
|
||
src/com/local/pawplay/
|
||
MainActivity.java # 全屏、沉浸式、返回键策略
|
||
CatPlayView.java # 单 View：场景调度、触摸、家长面板
|
||
Scene.java # 场景基类 + 粒子
|
||
FishScene.java
|
||
LaserScene.java
|
||
FeatherScene.java
|
||
Particle.java
|
||
SoundKit.java
|
||
res/ # 图标、字符串、4 个 WAV
|
||
keystore/ # 本机自签名密钥（已 gitignore，不提交）
|
||
tools/generate_sounds.py # 生成四段轻音效
|
||
screenshots/ # 实机截图
|
||
```
|
||
|
||
### 依赖
|
||
|
||
- JDK 17+
|
||
- Android SDK：Android 35 platform 的 `android.jar`
|
||
- Android 34 的 `android.jar`（给系统 `aapt2` 做资源链接；35 的资源表 Ubuntu 版 aapt2 读不了）
|
||
- build-tools 35 里的 `lib/d8.jar`
|
||
- `aapt2`、`apksigner`、`keytool`
|
||
- Python 3（只在重新生成音效时需要）
|
||
|
||
### 构建
|
||
|
||
```bash
|
||
git clone https://git.k1412.top/wuyang/pawplay.git
|
||
cd pawplay
|
||
TOOLCHAIN=/path/to/toolchain bash app/build.sh
|
||
```
|
||
|
||
如果 `build.sh` 没有执行权限，用 `bash app/build.sh` 即可。
|
||
|
||
可用环境变量覆盖：
|
||
|
||
- `ANDROID_JAR`：android-35/android.jar
|
||
- `RESOURCE_JAR`：android-34/android.jar
|
||
- `D8_JAR`：build-tools/35.0.0/lib/d8.jar
|
||
- `AAPT2`：aapt2 可执行文件
|
||
- `KEYSTORE` / `STOREPASS` / `KEYPASS`：签名密钥；不提供时会自动生成 `app/keystore/catplay.jks`
|
||
|
||
输出：`app/猫爪游乐场.apk`。
|
||
|
||
重新生成音效：
|
||
|
||
```bash
|
||
python3 tools/generate_sounds.py
|
||
```
|
||
|
||
### 技术要点
|
||
|
||
- 单 Activity + 自定义 `View`，`Choreographer` 驱动，`Canvas` 自绘，无 AndroidX、无 Gradle。
|
||
- 三个场景各自持有绘制状态和粒子池；多指触摸直接映射到场景，不依赖按钮。
|
||
- 家长面板也是 Canvas 绘制，命中区用 `RectF`；长按进度环和 2 秒阈值在 `CatPlayView` 内。
|
||
- 鱼群有目标游动、逃逸、boid 式分离和位置修正，避免叠在一起。
|
||
- 音效由 `tools/generate_sounds.py` 合成 44.1kHz/16-bit 单声道 WAV，`SoundPool` 播放。
|
||
- 全屏采用 `WindowInsetsController`（API 30+）和旧版 immersive flags；刘海安全区从 `DisplayCutout` 读取。
|
||
- 无任何网络或存储权限。
|
||
|
||
## 验证记录
|
||
|
||
- 实机：Xiaomi M367FC，Android 17 / SDK 37，2272×3408，400dpi。
|
||
- 竖屏、横屏都实际运行并截图。
|
||
- `dumpsys gfxinfo`：1191 帧，1 帧 janky（0.08%），50th 5ms，90th 10ms，99th 20ms。
|
||
- 返回键：第一次提示，第二次退出（实机验证）。
|
||
- 家长面板：长按打开、切换模式、**继续玩**关闭（修复了 1.0 里关闭动画卡在 1.0 导致看起来“没反应”的问题）。
|
||
- APK 无权限；安装后桌面图标正常。
|
||
|
||
## 已知限制
|
||
|
||
- 普通应用无法屏蔽系统级“上滑回桌面/侧滑返回”手势；需要更严格的防误触时，用系统的屏幕固定。
|
||
- 家长面板是自绘 UI，没有单独的 Android 无障碍节点；如需读屏支持可以再加。
|
||
- 本 APK 是本机自签名，适合自己安装，不适合直接上架应用商店。
|
||
- 猫对屏幕的兴趣差异很大；不感兴趣就换模式或换实体玩具，不要强迫。
|
||
|
||
## 开源协议
|
||
|
||
代码以 **MIT License** 开源，见 [LICENSE](LICENSE)。
|
||
Copyright (c) 2026 wuyang
|
||
|
||
如果这个项目让某只猫多扑了两下，欢迎在 Issues 里分享照片和反馈。
|
||
|
||
## 截图
|
||
|
||
| 横屏鱼池 | 横屏家长面板 |
|
||
| --- | --- |
|
||
|  |  |
|
||
|
||
| 横屏红点 | 横屏羽毛 |
|
||
| --- | --- |
|
||
|  |  |
|
||
|
||
| 竖屏家长面板 | 触摸反馈 / 返回提示 |
|
||
| --- | --- |
|
||
|  |  |
|