# 猫爪游乐场 · 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**。

![鱼池（横屏）](screenshots/05-fish-landscape.png)

## 三个模式

| 鱼池 | 红点 | 羽毛 |
| --- | --- | --- |
| 6–7 条锦鲤在水里游动、悬停、突然加速。爪子碰到鱼会变成气泡和星星，鱼过一会儿从边缘游回来。 | 经典红点。会停、会突然窜出去；爪子拍到它时整颗点会瞬移，并留下红色余晖。 | 三根暖色羽毛在阳光里慢慢飘。挥爪会带起风，羽毛被吹开、旋转，再慢慢落回来。 |
| ![鱼池](screenshots/01-fish-portrait.png) | ![红点](screenshots/03-laser-portrait.png) | ![羽毛](screenshots/04-feather-portrait.png) |

横屏是更舒服的玩法，竖屏也完整支持。全屏、无状态栏、无导航栏，屏幕常亮。

## 为什么这样设计（给猫，而不是给人）

- **猎物质感**：慢速游动 + 突然加速/停顿 + 方向变化，接近猫会追的小动物。
- **大目标**：鱼和羽毛都做得够大，猫不需要精确点中。
- **全屏任意触摸都有反馈**：不是只有“点中按钮”才算。多指、整只爪子拍下来都有水波、气泡或风。
- **没有失败**：没有分数、倒计时、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 里分享照片和反馈。

## 截图

| 横屏鱼池 | 横屏家长面板 |
| --- | --- |
| ![鱼池](screenshots/05-fish-landscape.png) | ![家长面板](screenshots/06-panel-landscape.png) |

| 横屏红点 | 横屏羽毛 |
| --- | --- |
| ![红点](screenshots/07-laser-landscape.png) | ![羽毛](screenshots/08-feather-landscape.png) |

| 竖屏家长面板 | 触摸反馈 / 返回提示 |
| --- | --- |
| ![竖屏家长面板](screenshots/02-panel-portrait.png) | ![触摸反馈](screenshots/09-touch-back.png) |