# Kitten-Parkour **Repository Path**: FSW_ei/Kitten-Parkour ## Basic Information - **Project Name**: Kitten-Parkour - **Description**: No description available - **Primary Language**: C++ - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-10 - **Last Updated**: 2026-04-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 🤖 Kitten Parkour ## 演示视频： - 抖音 「芯火小铺」 - 微信公众号、微信视频号、B站、小红书，全平台同名 **「芯火XH」** ## 交流群： 公众号回复【群】 一个运行在 ESP32-S3 上的双 OLED 猫咪跑酷游戏。项目使用 PlatformIO + Arduino 框架开发，主屏显示游戏画面，副屏显示分数、关卡、菜单和场景提示。玩家通过一个三轴摇杆控制小猫移动、跳跃、蹲伏，并在不同场景中躲避障碍物、持续前进、获得更高分数。 **适用人群**：Arduino/ESP32 初学者、电子爱好者、创客教育 **难度**：初级 ⭐⭐ --- ## 📋 目录 - [项目介绍](#项目介绍) - [所需硬件](#所需硬件) - [软件安装](#软件安装) - [硬件连接](#硬件连接) - [配置与编译](#配置与编译) - [游戏玩法](#游戏玩法) - [按键/摇杆说明](#按键摇杆说明) - [项目文件结构](#项目文件结构) - [常见问题](#常见问题) - [高级调整](#高级调整) --- ## 项目介绍 ### 这是什么？ Kitten Parkour 是一款双 OLED 显示的互动小游戏： - **左屏**（游戏屏）：显示小猫、障碍物、地形和背景 - **右屏**（信息屏）：显示关卡、分数、生命值、场景和菜单 ### 游戏特色 ✨ **完整的跑酷体验** - 左右移动躲避障碍物 - 向上跳跃、向下蹲伏 - 四种不同场景：沙漠、海洋、高山、草原 - 分数增长后自动升关和加速 ✨ **双屏显示** - 游戏画面和信息面板分开显示 - 画面更清晰，菜单也更直观 ✨ **中文界面** - 游戏标题、场景、菜单和结算提示均为中文 --- ## 所需硬件 ### 核心部分（必需） | 物品 | 数量 | 说明 | |------|------|------| | ESP32-S3 开发板 | 1 | 当前配置针对 esp32-s3-devkitc-1 | | SSD1306 OLED 屏幕 128×64 | 2 | I2C 接口，地址都是 0x3C | | 三轴摇杆模块 | 1 | 用于方向控制和按键确认 | | 杜邦线 | 若干 | 用于连接各组件 | | USB 数据线 | 1 | 用于供电和烧录程序 | ### 估算成本 - ESP32-S3 开发板：约 20 元 - 两块 OLED：约 10 元 - 摇杆模块：约 2 到 5 元 - 杜邦线和其他：约 5 元 - **总计**：约 40 元左右 --- ## 软件安装 ### 第1步：安装 VS Code 和 PlatformIO 1. 下载 VS Code： 2. 打开 VS Code，点击左侧扩展图标 3. 搜索 PlatformIO 4. 安装 PlatformIO IDE 5. 等待安装完成，第一次会自动下载工具链 ### 第2步：打开项目 1. 用 VS Code 打开本项目文件夹 2. 确认能看到 `platformio.ini` 3. 等待 PlatformIO 自动识别环境和依赖 ### 第3步：准备下载程序 如果你是第一次使用这个项目，建议先确认： - 开发板能被电脑识别 - USB 线支持数据传输 - PlatformIO 已正常安装 --- ## 硬件连接 ### 接线图说明 项目使用两路 I2C 总线连接两块 OLED。两块屏的地址都可以保持 0x3C，因为它们不在同一条 I2C 上。 ### OLED 屏幕 1 - 游戏屏 | 屏幕引脚 | 连接到 ESP32-S3 | 说明 | |---------|-----------------|------| | GND | GND | 电源地 | | VCC | 3.3V | 电源正极 | | SCL | GPIO 7 | 时钟 | | SDA | GPIO 6 | 数据 | ### OLED 屏幕 2 - 信息屏 | 屏幕引脚 | 连接到 ESP32-S3 | 说明 | |---------|-----------------|------| | GND | GND | 电源地 | | VCC | 3.3V | 电源正极 | | SCL | GPIO 2 | 时钟 | | SDA | GPIO 1 | 数据 | ### 摇杆接线 | 摇杆引脚 | 连接到 ESP32-S3 | 作用 | |---------|-----------------|------| | VRX | GPIO 4 | 左右移动、场景切换 | | VRY | GPIO 5 | 向上跳跃、向下蹲伏 | | SW | GPIO 15 | 开始、暂停、确认 | | VCC | 3.3V | 供电 | | GND | GND | 地线 | ### 接线注意事项 - 摇杆按键使用输入上拉模式，所以按下时会读到 LOW - OLED 和摇杆都建议使用 3.3V 供电 - 上电后程序会自动采样摇杆中心值，所以开机时尽量让摇杆处于中间位置 - 如果你的开发板 GPIO 分配不同，需要修改 src/main.cpp 顶部的引脚定义 --- ## 配置与编译 ### 第1步：确认开发板连接正常 1. 用 USB 数据线把 ESP32-S3 连接到电脑 2. 打开 VS Code 3. 确认 PlatformIO 能识别到项目 ### 第2步：检查项目配置 打开 `platformio.ini`，你会看到类似配置： ```ini [env:esp32s3-wroom-n8r2] platform = espressif32 board = esp32-s3-devkitc-1 framework = arduino ``` 如果你用的不是这个开发板型号，请根据实际情况调整 `board =`。 ### 第3步：编译 点击 PlatformIO 的 Build 按钮，或者使用命令： ```bash pio run ``` ### 第4步：上传 编译成功后点击 Upload 按钮，或者使用命令： ```bash pio run -t upload ``` ### 第5步：打开串口监视器 串口波特率设置为 115200： ```bash pio device monitor -b 115200 ``` --- ## 游戏玩法 ### 游戏目标 控制小猫不断前进，躲避障碍物，尽量拿到更高分数。碰到障碍会减少生命值，生命值归零后进入游戏结束界面。 ### 控制方式 #### 标题界面 - 左右推动摇杆：切换场景 - 按下摇杆按键：开始游戏 #### 游戏进行中 - 左右推动摇杆：控制小猫左右移动 - 向上推动摇杆：跳跃，海洋场景中会向上浮动 - 向下推动摇杆：蹲伏，海洋场景中会向下下潜 - 按下摇杆按键：暂停游戏 #### 暂停界面 - 上下推动摇杆：选择菜单项 - 按下摇杆按键：确认 暂停菜单包含： - 继续游戏 - 场景选择 #### 游戏结束界面 - 按下摇杆按键：重新开始 ### 场景说明 #### 沙漠 - 有太阳和远景山地 - 障碍以沙漠风格为主 - 起伏较小，比较适合新手 #### 海洋 - 有水线、气泡和海洋元素 - 角色会在水下上下浮动 - 玩法和其他场景差异最大 #### 高山 - 有山峰和更明显的地形变化 - 节奏更紧凑 - 对操作时机要求更高 #### 草原 - 地形较平稳 - 障碍节奏适中 - 适合练习基础操作 --- ## 按键/摇杆说明 ### 摇杆方向 代码中会根据摇杆偏移量判断操作： - X 轴偏右：角色向右移动 - X 轴偏左：角色向左移动 - Y 轴偏上：角色执行跳跃或上浮 - Y 轴偏下：角色执行蹲伏或下潜 ### 按键 摇杆按键是全项目最重要的确认键： - 标题界面：开始游戏 - 游戏中：暂停 - 暂停界面：确认菜单项 - 游戏结束：重新开始 ### 自动校准 程序启动后会读取 40 次摇杆值作为中心点，所以建议： - 上电时不要碰摇杆 - 如果发现方向偏移，重新上电再试一次 --- ## 项目文件结构 ``` Kitten Parkour/ ├── platformio.ini # PlatformIO 配置文件 ├── README.md # 项目说明文档 ├── src/ │ └── main.cpp # 主程序，所有游戏逻辑都在这里 ├── include/ │ └── README # 头文件目录说明 ├── lib/ │ └── README # 私有库目录说明 ├── data/ # 预留资源目录 └── test/ └── README # 测试目录说明 ``` ### 主要文件说明 #### `platformio.ini` 这里定义了： - 使用什么开发板 - 使用什么框架 - 需要安装哪些库 - 串口速度和上传速度 #### `src/main.cpp` 这里包含了： - 硬件初始化 - 摇杆读取 - 场景切换 - 碰撞检测 - 画面渲染 - 游戏状态机 --- ## 常见问题 ### 问题1：屏幕不显示内容 先检查： - SDA 和 SCL 是否接对 - VCC 是否接 3.3V - GND 是否接地 - 两块屏是否都已经通电 ### 问题2：摇杆没反应 先检查： - VRX、VRY、SW 是否接到了正确引脚 - 摇杆是否供电正常 - 开机时摇杆是否放在中间 ### 问题3：编译失败 先检查： - 是否已经安装 PlatformIO - 是否成功下载依赖库 - `platformio.ini` 中的开发板配置是否正确 ### 问题4：上传失败 先检查： - USB 线是否支持数据传输 - 当前串口是否被其他软件占用 - Windows 设备管理器里是否识别到了开发板 ### 问题5：串口没有输出 先检查： - 串口波特率是否为 115200 - 当前选择的串口是否正确 - 开发板是否已经成功复位并运行 --- ## 高级调整 ### 修改引脚 如果你想换接线，只需要修改 `src/main.cpp` 顶部这些定义： - `GAME_SDA_PIN` - `GAME_SCL_PIN` - `INFO_SDA_PIN` - `INFO_SCL_PIN` - `JOY_VRX_PIN` - `JOY_VRY_PIN` - `JOY_SW_PIN` ### 调整游戏节奏 如果你想让游戏更快或更慢，可以查看这些参数： - `FRAME_MS` - `gSpeed` - `gSpawnCooldown` - `updateStage()` 中的升级逻辑 ### 调整场景表现 以下函数分别控制不同视觉效果： - `drawSceneBackground()`：背景 - `drawSceneGround()`：地形 - `drawObstacle()`：障碍物 - `drawCat()`：角色动画 ### 调整刷新频率 信息屏刷新速度和主画面刷新速度是分开的。想优化流畅度时，可以查看： - `INFO_REFRESH_TITLE_MS` - `INFO_REFRESH_PLAY_MS` - `INFO_REFRESH_PAUSE_MS` - `INFO_REFRESH_GAMEOVER_MS` --- ## 已知行为 - 程序启动后会自动读取摇杆中心值 - 标题界面可以直接切换场景 - 暂停后可以返回标题界面再重新选择场景 - 两块 OLED 会以不同节奏刷新，减少不必要的重绘 --- ## 许可证 如果你打算公开发布这个项目，建议补充一个明确的许可证文件，例如 MIT、Apache 2.0 或 GPL。当前仓库未附带许可证声明。 --- 如果你是第一次接这个项目，建议先按“硬件连接”把两块 OLED 和摇杆接好，再进行编译和上传。只要标题界面能正常显示，就说明整套链路基本已经通了。 ## 后续扩展建议 - 增加声音反馈，比如碰撞音效或开始音效 - 增加更多场景和障碍类型 - 增加存档，把最高分保存到 Flash 或 LittleFS - 增加按键重映射或配置界面 - 增加标题动画和结算动画 --- 如果你是第一次接这个项目，建议先按“接线说明”把硬件接好，再用 PlatformIO 编译上传，最后看标题页是否能正常显示并切换场景。这样可以最快确认整套链路是否通了。