跳到主内容
芝麻园地
← 返回博客
#android#kotlin#jetpack-compose#live-wallpaper#wallpaperservice

用 AI 两天做出 Android 动态壁纸:从空工程到山洞水滴(Kotlin + WallpaperService)

用十条提示词推进 Android 动态壁纸的需求、设计与 Kotlin 实现,复盘 WallpaperService.Engine 继承、API 签名、帧内对象分配与不可见停帧的实践。

15 分钟

一句话:在 Android Studio 的空 Compose 工程上,用十条提示词、两个晚上,和 AI 一起把「山洞水滴」动态壁纸从需求聊到能在 Pixel 真机上跑起来——M1 骨架和 M2 水滴涟漪场景编译通过、单测全绿。这篇把协作过程、提示词原文和四个容易卡死人的技术坑一次讲清楚。

先交代背景。上一篇我记录了用 Tauri + Vue + WebGL 做 Windows 桌面「星际穿越」动态壁纸的过程。这次换个完全不同的战场:Android 手机原生动态壁纸,技术栈是 Kotlin + Jetpack Compose,工程是 Android Studio 新建的空项目,包名 com.example.livewallpaper。

和上次最大的不同是这次的协作节奏:第一句提示词就明确说了「我们先讨论一下需求」——不写一行码,先把方向聊明白。回头看,这个开头省掉了后面大量返工。

第一步:不写码,先聊透需求

我的第一句话是:

「我想做一个动态壁纸,这是 Android Studio 创建的空项目,我们先讨论一下需求。」

AI 没有急着开写,而是先做了三件事:

  1. 探查工程现状:读 AndroidManifest.xml、app/build.gradle.kts 和源码目录,确认技术底座——Kotlin 2.2.10、AGP 9.2.1、minSdk 29、targetSdk 36,标准 Compose 空模板。
  2. 讲清动态壁纸的技术骨架:它本质是一个常驻的 WallpaperService.Engine;渲染有三条路线(Canvas 2D / OpenGL ES / 视频循环);省电的生死线是「不可见就停帧」;设置页要挂在 settingsActivity。
  3. 给出推荐方案再抛问题:第一版定为「自然氛围系·山洞水滴」——贴合我平时喜欢的山洞水滴、布谷鸟这类安静环境音,视觉和声音双差异化;渲染走 Canvas 2D;单 Service + 多 Engine 可插拔架构。

最后抛了三个待拍板问题:主题方向、环境音默认开关、发布目标。这就是一份四层需求决策地图:主题内容 → 渲染引擎 → 核心能力 → 工程形态。

第二步:把讨论结论固化成需求文档

我对方向很满意,于是说:

「哎,这个设计需求我很满意。你把这个需求保存到项目目录,当我们的需求文档。」

需求文档 v0.1 落盘后,三个开放问题按建议拍板,升级为 v0.2:

决策点 拍板结果
主题 山洞水滴(预留「星际穿越」作为后续可插拔场景)
环境音 默认关闭,设置页里可手动打开
发布目标 自用 + 产出技术内容,不上架应用市场

接着一句话:「三个开放问题就按你的建议来。再为当前项目创建 Git 并提交。」——建立 42dd735 基线(48 个文件、1193 行),顺手校验了 .gitignore 确认 local.properties 和构建产物不会入库。

第三步:写码之前,先写系统设计

这里是我最刻意的一步:

「动手写代码前,我们先做一下这个系统设计,并把系统设计保存到当前项目中,以便以后我和别的 Agent 讨论系统设计方案,优化系统设计。」

这句话的目的不是走形式,而是让设计文档成为以后我和任何一个新 Agent 对话的公共上下文。系统设计文档里包含:三层架构(设置层 / 壁纸层 / 渲染层 + 音频旁支)、Mermaid 架构图、包结构、引擎生命周期表、渲染器接口、山洞六层场景拆解、音频设计、配置传递、省电策略,外加一张8 项关键权衡表和 M1–M6 里程碑。提交为 0ef9681。

第四步:M1 骨架——第一个硬坑就来了

「开始实现吧」之后,AI 搭出了壁纸服务骨架:LiveWallpaperService、WallpaperRenderer 接口、M1 空场景的 CaveRenderer(深色渐变 + 呼吸微光)、res/xml/wallpaper.xml、Manifest 注册(BIND_WALLPAPER 权限 + intent-filter + meta-data)。

编译时踩了三个坑,第一个是架构级的:

坑一:Kotlin 不能直接继承 WallpaperService.Engine

直觉写法是单独定义一个类继承 Engine:

// 编译不过
class CaveEngine(service: LiveWallpaperService) : service.Engine() { ... }

编译直接失败。原因是:WallpaperService.Engine 在 Java 里是一个 inner class(非静态嵌套类),它持有外部 Service 实例的引用;而 Kotlin 语言规范禁止把 inner class 当作 supertype——你没法在继承时给它一个外部类实例。

Google 官方示例的解法是:把 Engine 子类定义在 Service 类内部,让它天然持有 outer Service 实例。渲染器则不受这个限制,用接口解耦,仍然可以是独立文件、随时插拔新场景。

这个坑的价值在于它是「语言规范级」的,不是查个文档改个参数就能绕过去的。它直接决定了整个包结构:引擎必须贴着 Service 写,渲染器才能自由独立。

坑二:Engine 的 API 签名别想当然

  • onCreate(SurfaceHolder) 是带参数的;
  • onTouchEvent 返回 Unit(void),不是事件消费布尔值;
  • onOffsetsChanged 有 6 个参数。

凭记忆写 override,签名对不上就会默默写进一个没人调的新函数里。

坑三:依赖版本反向要求 compileSdk

androidx.core:core:1.19.0 要求 compileSdk ≥ 37,于是升到 compileSdk 37.2(本机已装该 platform,targetSdk 保持 36 不动)。

这些实现期发现,全部回写进系统设计文档的变更记录,而不是只躺在代码里。最后 gradlew assembleDebug 一次通过,APK 约 29.8 MB。

第五步:M2 场景——水滴、涟漪与「帧内零分配」

「你继续吧」之后进入真正的画面:

  • WaterDropSystem:重力水滴粒子,用对象池复用,触水时回调产生涟漪事件;
  • RippleSystem:涟漪半径线性扩散、透明度线性衰减,用扁平椭圆模拟水面透视,同样对象池;
  • CaveRenderer 升级为分层场景:背景渐变 + 呼吸光 → 钟乳石剪影(确定性随机生成)→ 水面 → 涟漪 → 水滴。

这里有个关键性能纪律:所有 Shader / Path 在 onSurfaceCreated 里预建,onFrame 帧内零对象分配。逐帧 new Paint、new Path、new 粒子对象,GC 就会在屏幕上掉帧。每帧只改 paint 的 alpha 和池内对象的状态。

配套写了单元测试 WallpaperSceneTest,3/3 通过:水滴下落恰好触水一次、涟漪到半径上限回收、涟漪透明度衰减到零回收。粒子的状态机逻辑是纯计算,不碰 Android API,所以能直接在 JVM 测试里跑——这也是把渲染状态拆成可测纯逻辑的回报。

第六步:「为什么只显示 Hello Android?」

装到手机上打开 App,我看到的是一个写着 Hello Android 的空界面。这其实是每个第一次做动态壁纸的人都会撞的墙:

「为什么我通过 Android Studio 运行的时候,界面就显示了一个 Hello Android?」

答案是:那个 MainActivity 只是 Compose 模板自带的占位页,动态壁纸根本不在 App 里展示。它要到系统壁纸选择器里才能预览和绑定。我用的是 Pixel,完整路径是:

长按桌面 → 壁纸与样式 → 更换壁纸 → 动态壁纸 → 山洞水滴 → 预览 → 应用(可选主屏幕与锁屏)。

另外一个只有做过才知道的细节:预览模式(isPreview())下系统不允许发声,所以环境音要在预览时强制静音——这条记进了设计文档,留给 M4 实现。

关键技术决策速查表

主题 结论
引擎继承 Engine 是 Java inner class,Kotlin 禁止其作 supertype → 引擎必须写在 Service 内部;渲染器用接口解耦保持可插拔
Engine API onCreate(SurfaceHolder) 带参;onTouchEvent 返回 Unit;onOffsetsChanged 六参
compileSdk androidx.core 1.19.0 要求 ≥ 37,targetSdk 仍保持 36
帧内零分配 Shader/Path 在 onSurfaceCreated 预建;粒子走对象池;onFrame 只改 alpha 与池内状态
省电 onVisibilityChanged(false) 是唯一权威停帧停声信号,logcat 可验证渲染循环 start/stop
预览声音 isPreview() 时系统不允许声音,M4 实现时强制无声

这套协作方式收获的几条经验

  1. 第一句就说「先讨论需求」:空工程上最值钱的动作不是写码,是把主题、渲染路线、发布目标先拍板,后面才不会推倒重来。
  2. 需求和设计都要落盘成文档:v0.2 需求文档 + v0.1 系统设计,是我下次和任何新 Agent 继续聊的公共上下文,不用重新解释一遍。
  3. 实现期的发现回写设计文档:Kotlin 继承限制这种架构级结论,只留在代码里三个月后就没人记得。
  4. 语言规范级的坑要单独标注:inner class 继承问题不是「报错→百度→改」,它决定了包结构,值得写进决策表。
  5. 状态机逻辑写成可单测的纯函数:水滴触水、涟漪回收这类规则,脱离 Android 框架在 JVM 里测,反馈最快。
  6. 给读者写清验证路径:「Hello Android」不是 bug,是不知道去壁纸选择器里看——App 类项目最容易缺的就是这段引导。

下一步

当前进度到 M2,按系统设计的里程碑后面还有:

  • M3:触摸交互(点水面起涟漪、点顶部惊落水滴)+ 翻页视差;
  • M4:环境音(SoundPool 水滴 + 布谷鸟声,默认关,声音素材来源待定);
  • M5:Compose 设置页 + 配置联动 + settingsActivity;
  • M6:省电验证、性能打磨、预览降级。

另外还有个待拍板项:把那个「Hello Android」的 MainActivity 改成**「一键设置壁纸」引导页**,省得每个装包的人都问一遍去哪设置。

说明:M3 之后的触摸、环境音、设置页均为设计目标,尚未实现;本文涉及的 APK 为 debug 构建(约 29.8 MB),未做上架优化。