正在连接信源…

Papaya Pathfinder 复刻全流程

Papaya Pathfinder 从采购、打印、组装到装软件、标定和训练的 86 个步骤,附物料表、购买链接与官方出处。

Papaya Pathfinder 是一系列基于 ESP32 的小型遥控轮式探测车。仓库提供 Papaya Pathfinder 和 Papaya Pathfinder Mini 的完整 3D 打印机构、STEP 格式 CAD 文件、元件清单、接线图及固件说明。

采购

  • 采购巡检车部件

    根据尺寸、电机和电源需求选择巡检车变体,并购买 ESP32 控制器、BTS7960 电机驱动器、GA25 减速电机、MS24 舵机、3S 锂聚合物电池及两个 UBEC。ELRS 接收机仅在运行 firmware-elrs 时需要。

  • 准备 WiFi 固件用摄像头 ESP32

    运行 `firmware-wifi` 时使用带摄像头的 ESP32,可选 ESP32-CAM 或 ESP32-S3-CAM。

  • 准备 ELRS 固件用接收机

    仅在使用 `firmware-elrs` 运行时需要 ELRS 接收机。

  • 准备六个 N20 直流减速电机

    准备 6 个 N20 直流减速电机。

  • 准备 2S 锂聚合物电池

    使用 LiPo 2S 作为电源。

  • 准备五伏降压稳压器

    准备一个输出 5V 的 DC-DC 降压稳压器,供 ESP32 或 ESP32-CAM 使用。

  • 准备六伏降压稳压器

    准备一个输出 6V 的 DC-DC 降压稳压器,供 N20 电机使用。

打印与加工

  • 打印机械零件

    所选变体的所有机械零件均可完全 3D 打印,模型位于该变体的 3d-models/ 目录中。打印该目录提供的模型即可制作机械零件。

  • 下载全部 rover STL 文件

    从 `pathfinder-mini/3d-models/` 获取该探测车的所有 STL 文件。

  • 获取完整 STEP 机械设计

    完整机械设计也以 STEP 格式提供,文件为 `pathfinder-mini/cad/papaya-pathfinder-mini.step`。

  • 选择结构件与轮胎打印材料

    结构零件使用 PETG 或 PLA,轮胎使用 TPU。

  • 打印六个 TPU 轮胎

    打印 6 个 `tire.stl` 轮胎,材料为 TPU。

组装

  • 确认应用原生文件

    确认原生文件位于 `android/app/src/main`。游戏不使用的旧 GLB 不会进入 APK,但 rover FBX 会被包含。

  • 使用 M3 螺钉螺母组装

    所有零件均设计为使用 M3 螺钉和螺母组装。

软件与固件

  • 安装依赖

    使用 Node.js 22.12 或更高版本以及 npm,在项目根目录安装依赖。

  • 启动开发服务器

    运行开发服务器,然后在终端打开 Vite 打印的 URL。开发期间的代码更改会立即反映。

  • 通过手机访问游戏

    让手机与计算机处于同一 Wi-Fi 网络,在手机浏览器中打开计算机的本地 IP 地址和 Vite 显示的端口,例如 `http://192.168.1.50:5173`。计算机防火墙必须允许此连接。

  • 构建网页发行版本

    运行构建命令。编译结果生成在 `dist/` 中,包括 `index.html`、`assets/`、`papaya-pathfinder.fbx` 和从 `public/` 复制的 `model.glb`。

  • 预览本地构建

    在本地预览已构建的网页版本。

  • 安装 JDK 17 或更高版本

    除网页依赖外,还要安装 JDK 17 或更高版本,并确保 `java`、`javac`、`jar`、`keytool` 可用。该 APK 使用 JDK 21 构建。

  • 安装 Android SDK 平台与构建工具

    Install Android SDK Platform 35 and Android SDK Build Tools, with version 36.1.0 having been used. These SDK components can be installed through Android Studio's SDK Manager, and Android Studio does not need to be open to generate the APK.

  • 设置 SDK 路径环境变量

    构建脚本会在 macOS 的 `~/Library/Android/sdk` 和 Linux 的 `~/Android/Sdk` 中自动查找 SDK。若安装在别处,请设置 `ANDROID_HOME` 或 `ANDROID_SDK_ROOT`,例如在 macOS 上执行 `export ANDROID_HOME="$HOME/Library/Android/sdk"`。

  • 用 JAVA_HOME 选择 JDK

    将 `JAVA_HOME` 设置为所需 JDK 的安装目录,即可选择特定的 JDK 版本。

  • 选择已安装的构建工具版本

    可以通过 `ANDROID_BUILD_TOOLS` 选择已安装的 Build Tools 版本,例如设置为 36.1.0。这些打包说明适用于 macOS 和 Linux。

  • 在项目根目录生成 APK

    在项目根目录运行 `npm run android:apk`。该命令先用 Vite 构建网页版本,把 `dist/` 中的文件复制到 APK 的本地资源(排除未使用的旧版 `model.glb`),编译 Android 资源和 Java 源代码并生成 DEX 字节码,然后对齐 APK、用本地开发密钥签名并验证签名与对齐。

  • 确认生成的 APK 输出文件

    生成的输出文件位于 `artifacts/papaya-pathfinder-debug.apk`。

  • 构建新的 Android APK

    更改游戏后运行 Android APK 构建命令。

  • 覆盖安装新的 APK

    不要卸载现有应用,直接将新 APK 覆盖安装到之前版本上。

  • 保留开发签名密钥

    保留 `android/build/debug.keystore`;更新必须使用同一个密钥,才能覆盖安装并保留数据。删除整个 `android/build/` 目录也会删除此密钥。

  • 生成开发版 APK

    在项目目录运行打包命令,生成包含游戏且无需服务器或网络连接的安装包。

  • 定位生成的 APK

    在 `artifacts/papaya-pathfinder-debug.apk` 找到生成的开发 APK。

  • 安装编译工具链

    Install Node, JDK 17 or newer, Android SDK Platform 35, and Android SDK Build Tools.

  • 配置 Android 工具路径

    脚本会检测 macOS 和 Linux 的常用 SDK 路径,也可使用 `ANDROID_HOME` 或 `ANDROID_SDK_ROOT`、`JAVA_HOME` 和 `ANDROID_BUILD_TOOLS` 指定位置。

  • 保留开发签名密钥

    保留 `android/build/debug.keystore` 中的开发密钥。它不会提交到 Git,可让新构建覆盖安装旧构建并保留进度。

  • 选择通信固件

    firmware-wifi 提供基于 WiFi 的控制和用于移动命令的 HTTP API,可配合 Python 桌面控制器或 Android 应用使用。firmware-elrs 使用 ExpressLRS 控制。

  • 选择 WiFi 固件配置

    `firmware-wifi` 提供基于 WiFi 的控制、通过 HTTP API 发送移动命令,以及通过 WiFi 进行实时视频流传输。

  • 选择 ExpressLRS 固件配置

    `firmware-elrs` 使用 ExpressLRS(ELRS)控制。

  • 选择 Python 桌面控制器

    Python 桌面控制器显示实时视频,并通过 HTTP 向探测车发送基于游戏手柄的控制命令。

  • 选择 Android 移动控制应用

    Android 应用显示实时视频,并支持使用游戏手柄控制探测车,提供与桌面控制器相同的驾驶体验。

标定与测试

  • 验证 APK 打包结果

    打包过程会自动验证 Java/DEX 编译、APK 签名和对齐。

  • 在真实设备上检查应用

    在真实设备上检查应用的功能和性能。

用起来

  • 发布网页版本

    将 `dist/` 的全部内容复制到静态托管服务,并从域名或子域名的根目录提供。当前配置使用 `/assets/` 和 `/papaya-pathfinder.fbx` 等绝对路径。

  • 提供完整游戏文件

    不要只复制 `index.html`,还必须提供 JavaScript 和模型文件。通过 HTTP 或 HTTPS 提供游戏;直接使用 `file://` 打开 HTML 可能导致模块和资源无法加载。

  • 复制 APK 到手机并安装

    把该文件复制到手机上并打开以安装应用。Android 可能会要求允许来自文件管理器或浏览器的安装。应用需要 Android 8 或更高版本,并需要支持 WebGL 2 的 WebView。

  • 选择赛道并开始比赛

    从六个赛道中选择一个,点击 **Correr**,与红色 rover 比赛。

  • 等待三秒倒计时开始

    比赛开始时,两个 rover 会被放到网格上,并进行三秒倒计时。

  • 查看赛道距离和时间限制

    开始前,选择器显示赛道距离,面板显示检查点数量和时间限制。

  • 按顺序通过检查点

    按编号顺序驶过赛道检查点,最后一个检查点标记为 **META**。

  • 跟随下一个检查点

    下一个检查点以金色突出显示,赛道会出现在地图上。比赛面板显示已用时间和对手通过的检查点数量。

  • 完成圈并记录成绩

    即使红色 rover 先完成,你仍可以完成自己的圈并记录时间。每个赛道的个人最佳成绩分别保存。

  • 取消比赛或重新比赛

    使用 **Abandonar** 取消比赛,或在完成后使用 **Repetir**。比赛结束时,红色 rover 会恢复巡逻。

  • 打开轨道地球视图

    按 M 或轻触 PLANETA 打开轨道地球视图。

  • 旋转地球视图

    拖动可自由旋转地球,包括越过两极;拖动灵敏度会随当前高度下可见地面尺度变化,并在松开时停止。

  • 缩放地球视图

    滚动鼠标或使用 +/− 缩放,可接近至距地表八米以内。

  • 观察地形加载与混合

    附近地形会在显示前开始加载;在1,800米至100米之间,轨道地球会逐渐混合到实际流送的地形、岩石、结构和探测车中。

  • 下降至目标位置

    选择 Descender aquí,将探测车置于视图中心;此时只加载附近的目的地地形。绿色标记表示探测车,金色标记表示着陆区域。

  • 返回探测车

    选择 Volver al rover、按 M 或 Escape 可在不移动探测车的情况下返回。查看地球时游戏会暂停;下降到新位置会取消当前比赛。

  • 使用向上推进

    向上推进在平地静止时可产生约1.8米的跳跃,没有冷却时间;每次按下都会沿探测车局部向上轴增加动量,在空中也有效。

  • 控制空中推进器

    在空中,W/S或左侧触摸摇杆控制前进/反向推进器,A/D使探测车绕自身轴旋转,方向键或右侧触摸摇杆控制横向推进器。

  • 制动水平漂移

    按 Space/Freno 可制动水平漂移。推进器尾焰会朝请求推进方向的反方向转动,并在施加推进时保持可见。

  • 按住 G 持续推进

    按住 G,或在触摸屏上切换“Rápido”,可获得持续强力推进;W + G 的前向加速度最高为 1,800 m/s²,反向或侧向加速度为 60 m/s²。

  • 控制上升与短促冲量

    按 Z / Subir 可执行稳定的径向上升;F 会沿探测车倾斜方向施加一次短促冲量。在空中时,G 与 W/S 或左右方向键组合可切换到定向飞行。

  • 保持高度并降落

    动力飞行启动后,松开垂直输入会保持当前高度;按 X 可下降,实际接触地面后恢复正常驾驶。G 本身不会命令上升,松开 W 时即使仍按住 G 也只会滑行而不会切换到升力。

  • 使用高速行星飞行

    前向加速会逐渐达到 6,000 m/s 的巡航速度,接近地面时速度降低;高速飞行使用更粗略的地形图块和更大的局部框架,接近地表时恢复精细碰撞。

  • 检查桌面渲染限制

    游戏期间桌面渲染限制为 60 FPS,玩家空闲时限制为 30 FPS;隐藏的标签页会暂停模拟和渲染。Retina 帧缓冲区的像素比限制为 1.5×,像素总数限制为三百万,并保留 HDR、接触阴影和 2× MSAA。

  • 验证空中地形碰撞

    空中移动会沿完整的三维路径检测车体和六个轮胎与地形、岩石的碰撞。离地高度低于 80 m 时,低空飞越会逐步消耗过多水平速度,撞击也会消散飞行速度。

  • 体验地面轮式推进

    向前驾驶会自动使用轮式推进器辅助,正常巡航速度为 8 m/s;比赛中玩家与对手共用 7 m/s 的速度限制。制动或滑行会停止辅助,普通地面驾驶不显示推进器动画。

  • 起飞、移动与下降

    按 Z 让漫游者离开地表,按 W/S 前后移动,按 A/D 旋转,按 X 下降。

  • 高速行星表面旅行

    在当前高度按住 W + G 可快速进行行星旅行。G 独立控制速度,只有想爬升时才按住 Z。

  • 滑行时保持高度

    释放垂直推力时,飞行控制器会保持当前高度,因此滑行不会使漫游者继续上升。

  • 调整俯仰角

    按住上方向键可将机头向下俯仰至 85°,按住下方向键则抬高机头。松开按键后,所选俯仰角会保留。

  • 横移与转向

    左右方向键提供横向推力。A/D 转向时带轻微倾斜,高速下加强转向仍保持灵敏。

  • 制动与自动调平

    按空格可制动并调平漫游者,按 X 可使其调平以进行受控着陆。释放推力时,垂直运动会平滑减速并进入悬停。

  • 高空场景与摄像机变化

    高度增加时,同一游戏场景会显示弯曲的地球、转为黑暗星空,并调整摄像机以展示下方星球。仍可拖动鼠标环顾四周。

  • 远景细节与下降恢复

    高空飞行时,远距离地表使用粗糙球形 LOD,详细区域和接触阴影会休眠,下降时恢复。此飞行路径没有轨道视角切换或传送。

  • 接近并着陆

    按住 X 可接近并降落在任意位置。接近地面时下降速度会减慢,撞击会消散飞行能量,轮胎实际接触地面后恢复正常漫游者驾驶和摇臂转向悬挂。

  • 查看独立的检查视角

    可选的 M/PLANETA 检查视角与连续飞行视角保持独立。

  • 探索行星区域

    飞离着陆区后,任务面板会显示当前区域,并引导你前往附近地点;附近区域会包含岩石、废弃探测器、地质站和远征信标。

  • 登记探索发现

    停在附近地点七米以内,按住 E / Escanear 2.5 秒,即可登记一个发现。发现记录保存在浏览器或 Android WebView 的本地存储中。

  • 用左摇杆驾驶

    在触摸设备上,用比例左摇杆控制前进、倒车和转向。小幅推动可获得更柔和的输入,摇杆中心设有死区。

  • 用第二摇杆控制飞行

    进入飞行模式后,第二摇杆会显示出来,用于控制机头俯仰和横向推力。

文档