Pokedex-AR开发者教程：5步向AR场景添加一只新宝可梦（从Poly模型到.sfb导入）
项目地址: https://gitcode.com/gh_mirrors/po/Pokedex-AR Pokedex-AR 是基于 ARCore + Sceneform 的 AR 宝可梦示例应用，结合 Hilt、Coroutines + Flow、MVVM 架构等现代 Android 技术栈，将 3D 宝可梦模型渲染进真实环境。本教程以「新增一只宝可梦」为主线，用 5 个步骤讲清从 Poly 挑选 3D 模型、Sceneform Viewer 转换 .sfb，到最终在 AR 场景中看到它的完整流程，新手也可以跟着做。
如果本地还没有项目，先执行：
git clone https://gitcode.com/gh_mirrors/po/Pokedex-AR
第1步：从 Google Poly 获取 3D 模型并转换成 .sfb 🎯
- 在 Poly 上搜索你喜欢的宝可梦造型，下载
.glb格式模型 - 项目现用的宝可梦与精灵球模型出自艺术家 Tipatat Chennavasin，花园场景来自 Poly by Google，均采用 CC-BY 3.0 许可（商用需保留署名）
- 用 Sceneform Viewer（Android Studio 插件）打开
.glb，转换为：.sfb：静态渲染文件，运行时真正加载的就是它.sfa：动画文件
第2步：把 .sfb 导入 assets 目录 📦
将转换好的文件复制到 App 模块的资源目录 app/src/main/assets/ 下，每个宝可梦一个 .sfb 文件。项目已内置 15 个示例模型（pikachu.sfb、snorlax.sfb 等），可作为对照。
此外，app/sampledata/ 保留了各宝可梦的模型源文件（如 pikachu/pikachu.sfa、pikachu/pikachu.sfb）以及 3D 模型的 Garden_BaseColor.png 贴图，方便理解模型与贴图的关系。
第3步：在 PokemonModels.kt 中注册新宝可梦 🧩
打开核心模块 pokedexar-core/src/main/java/com/skydoves/pokedexar_core/PokemonModels.kt，为每只宝可梦定义一个 RenderingModel（字段含义见 RenderingModel.kt 注释：名称、模型文件名、朝向、缩放、位置）：
fun getTotodile() = RenderingModel(
name = "totodile",
model = "totodile.sfb",
scale = 1.2f
)
💡 scale 决定模型在现实中的大小：项目里 Jigglypuff 是 0.45f、Snorlax 是 3f、精灵球仅 0.1f，按你模型的实际比例微调即可。
第4步：接入名称映射与随机抽取 🔁
这一步让新宝可梦能被详情页和捕捉页找到，共 3 个小改动：
getPokemonByName()：增加"totodile" -> getTotodile()分支（详情页按名字取模型，找不到会兜底返回 Eevee）getRandomPokemon()：增加对应分支，⚠️ 同时把Random.nextInt(13)改成Random.nextInt(14)——这是最容易被漏掉的一处PokemonUtils.getPokemonId()：在app/src/main/java/com/skydoves/pokedexar/utils/PokemonUtils.kt中补充名字→图鉴 ID 的映射（如pikachu -> 25）。该 ID 会被SceneRepository用于将捕捉次数持久化到 Room 数据库
第5步：编译运行，验证 AR 场景效果 ✅
- 需要支持 ARCore 的 Android 真机（
AndroidManifest.xml已声明android.hardware.camera.ar特性与com.google.ar.core = required） - 进入捕捉页后，相机追踪状态进入 TRACKING 即自动创建锚点，随机渲染一只宝可梦 + 精灵球，点击球体完成「捕捉」并记录 hits
- 详情页（
DetailActivity）会在 Garden 场景中渲染指定宝可梦，适合单独验收新模型的比例与朝向
新增宝可梦常见踩坑速查
| 问题 | 快速解决办法 |
|---|---|
| 模型太大，占满整个画面 | 调小 RenderingModel 的 scale |
| 模型不显示 | 确认 .sfb 已放入 assets/ 且文件名与 model 字段完全一致 |
| 模型不播放动画 | 检查对应的 .sfa 动画文件是否正确导入 |
| 捕捉后次数不增加 | 检查 PokemonUtils.getPokemonId() 是否漏加映射 |
| 随机抽不到新宝可梦 | 检查 getRandomPokemon() 的 nextInt 上限是否已 +1 |
总结
整条链路可以概括为：Poly 取模型 → Sceneform Viewer 转 .sfb → 放入 assets → 在 PokemonModels.kt 注册 → 接入映射并验证。掌握这 5 步，你就能随时扩展 Pokedex-AR 的宝可梦阵容，并顺带理解 ARCore 锚点、Sceneform 模型加载与 MVVM 数据流的协作方式。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
