宠物是什么？
宠物是一种精灵——一个包含多种不同动画的单一控件，可以按需在它们之间切换。每个动画都是一种模式（也称为状态或阶段）：比如"Idle"、"Run right"、"Jumping"等。
来自 Codex 或 Petdex 风格包的宠物通常自带 9 种模式，例如 Idle、Run right、Run left、Waving、Jumping、Failed、Waiting、Running 和 Review。每种模式都有自己的帧循环，由你决定播放哪一种以及何时播放。
这就是整体思路：一个控件，多种行为，由你的条件来切换。
从技术层面来看，LVGL 没有多状态精灵的原生概念——我们在 LVGL 动画图像控件的基础上构建了这一功能，让所有模式都为你预先连接好了。完整背景请参阅什么是精灵？。
为什么使用宠物？
宠物的存在是为了给你的 ESP32 或 LVGL 项目注入生命力。精灵不再是一张静态的脸或单个循环动画，而是会做出反应：根据设备实际发生的情况切换模式。
最初的灵感来自代码伴侣。想象一下 Codex 风格的屏幕，一个小角色对你的编程会话做出反应：思考时处于 Idle 状态，读取 diff 时进入"Review"模式，构建失败时显示"Failed"。宠物通过动作表现应用当前的状态。
PicoPixel 更进一步：**任何你能表达的动作或触发条件，都可以制作成动画。**几个例子：
- 当温度读数超过阈值时切换到 Jumping。
- 从 API 获取数据时播放 Running，收到响应后回到 Idle。
- 传感器检测到运动时触发 Waving，请求超时时显示 Failed。
如果你的项目有值得展示的状态，宠物就是一种快速、富有表现力的展示方式——完全不需要你编写任何动画代码。
从目录中挑选宠物
首先创建一个 PicoPixel 账号，然后前往 picopixel.io/pets 的宠物目录。
浏览宠物库，找到你喜欢的角色，然后打开其详情页面。
在宠物的详情页面上，点击添加到项目。PicoPixel 会导入该宠物并在项目管理页中创建对应项目——无需任何设置，无需文件管理。
你刚刚获得了什么
添加宠物会创建一个包含单个 Sprite 控件的项目，其中预加载了该宠物附带的所有模式。打开后，你会在画布上看到精灵，右侧面板列出了所有模式——Idle、Run right、Run left、Waving、Jumping 等——每个都有自己的帧数和持续时间。
如果你对 Sprite 控件还不熟悉，什么是精灵？指南详细解释了模式、帧和持续时间。
切换到 Assets 标签，你会发现同一个精灵作为可复用组件保存在项目的本地库中。这是将宠物移入真实项目的关键所在。
使用宠物的三种方式
导入宠物后生成的项目主要用于存放这个角色。以下是将其添加到你真正想构建的项目中的三种方式。
1. 复制粘贴图层
最快捷的方式：在宠物项目中选中精灵图层，复制，打开另一个项目，然后粘贴。复制后的精灵会保留所有模式。适合一次性使用——如果你只需要在一个地方使用这个宠物，这样就完成了。
2. 将宠物设为库（推荐用于重复使用）
如果你打算在多个工作区使用该宠物，请将其项目转换为库。发布文件后，包括该精灵在内的资源就可以在团队工作区的任何地方导入使用。
发布步骤：
- 在宠物项目中，打开 Assets 标签并选择Add library（添加库）。
- 点击Publish（发布）。
然后，从其他项目中使用时：
- 打开你的新工作区或现有工作区。
- 选择Add library（添加库）。
- 从**SHARED LIBRARIES（共享库）**列表中链接宠物的库，如下图所示。
链接后，精灵就会出现在该工作区的 Assets 中。将其拖入画布即可使用，所有模式和设置都会一同保留。
库是用于团队内部重复使用的，而不是向公众发布的。关于库包含哪些内容、发布如何运作以及链接库显示在哪里的详细说明，请参阅库和可复用组件指南。
3. 修改项目属性以匹配你的硬件
你也可以直接编辑宠物项目的属性（屏幕尺寸、目标开发板）以匹配你的设备，然后在其中直接构建。这种方法可行，但不是推荐的路径：你会失去宠物和实际项目之间的清晰分离，而且宠物项目是作为展示而非模板来设置的。请优先考虑选项 1 或 2。
连接起来：让宠物做出反应
只播放 Idle 无法充分发挥宠物的作用。真正的价值在于事件编辑器，在那里你告诉它何时切换模式。
配置思路很简单：**当某件事发生时，切换到某个模式。**选择触发器——按钮按下、数值变化、定时器——然后选择 Set Sprite Mode 动作和要播放的模式。
在下面的截图中，我们在 JUMP! 按钮上添加了一个事件：点击时，动作将精灵的模式设置为 Jumping，因此宠物在按下按钮的瞬间就会跳跃。
将触发器替换为你的项目所提供的任何内容——传感器读数、API 调用完成、定时器触发——同样的连接就能让宠物对其做出反应。有关触发器、来源和动作的完整说明，请参阅使用事件编辑器。
需要注意的几点
以下几个好习惯能让你的宠物在真实硬件上表现良好、运行顺畅。
- **删除你不会用到的模式。**这是强烈建议的做法。保留的每个模式都意味着更多帧存储在内存中，而未使用的模式是纯粹的开销。对于存储或内存受限的开发板来说，精简尤为重要——删除任何你不打算触发的模式。
- **别忘了事件。**宠物本身不会做任何事。如同我们上面连接 JUMP! 按钮一样，使用事件编辑器为每个想要播放的模式添加条件。
- **注意设备的内存。**动画图像需要足够的 RAM 来存储帧。让你的编码助手查看导出的 LVGL 代码中的
README.md文件（里面有说明），或者自行确保已为动画图像分配了足够的内存。如果刷入后精灵没有显示，几乎肯定就是这个原因。
精灵可能占用较多内存。在小型微控制器上，一个包含所有 9 种模式和大尺寸帧的宠物可能耗尽内存而无法渲染。将其精简为你实际使用的模式，并确认你的 LVGL 配置为动画图像分配了足够的 RAM。
