Kotlin Multiplatform游戏移植实战：核心逻辑跨端复用

先说明一个容易混淆的地方Kotlin Multiplatform 这个“移植”和 FreeRTOS、LVGL、STM32 那边的“移植”不是同一类事。嵌入式移植是把代码从一种芯片平台搬到另一种硬件平台重点是寄存器、驱动、内存布局。而 KMP 移植是解决“同一套业务逻辑能不能在 Android、iOS、桌面端复用”的问题。你要不是搞跨端开发光看“移植”这个词确实容易误解成和固件、板子有关的活。如果把“星球突击队”这个游戏项目从单一 Android 工程迁到 Kotlin Multiplatform最值得关注的东西不是界面怎么写而是玩法逻辑、状态变更、得分规则、道具生成这些核心代码能不能只写一遍就同时在多个端跑起来。“星球突击队”这种带实时反馈、帧循环、碰撞判定和关卡状态的小游戏恰好适合拿来验证 KMP 的边界哪些代码可以共享哪些必须留给平台自己实现抽象做得不好会是什么结果。这篇文章按我实际做完一轮 KMP 改造的思路来拆不绕弯直接讲哪些代码要先下沉、哪些接口要抽象、哪些坑会在真机上冒出来。1. 移植前先分清哪些代码属于“游戏内核”哪些属于“平台外壳”不建议一上来就把整个项目拖进 KMP更不建议第一条就用 Compose Multiplatform 重写界面。先站在模块边界上把游戏拆成两层后面会省一大半事。1.1 游戏内核应该只描述规则不接触屏幕和按键“星球突击队”如果是一架飞船在屏幕上移动、发射子弹、抵抗一波波敌人那真正容易被跨端复用的是这样一些部分飞船坐标、速度、生命值、火力等级的变化规则敌人生成的时间表、移动路线、攻击模式子弹、敌机、障碍物之间的碰撞判定得分、连击、关卡、任务目标的计算游戏状态机待机、运行中、暂停、结算、重开这些逻辑有个共同点它们只依赖时间步长和输入指令不依赖你用的是触摸屏、鼠标键盘还是手柄。拿到同一个时间片就算出下一帧所有实体的位置和状态。这恰好是 KMP 最擅长共享的部分。我在实践里会把这一层命名为GameCore里面不出现Context、Activity、View、Bitmap、NSView这些平台类型也不建议直接依赖 Android 的SensorManager或 iOS 的UIDevice。需要用到的加速度计方向、键盘偏移这类数据都通过参数传进来或者通过接口暴露。1.2 平台外壳负责输入、渲染、音效和存档可以不强求统一游戏里最典型的平台差异来自四个地方输入Android 上可能是触摸拖动、虚拟按键桌面端可能是键盘方向键、鼠标点击。渲染Android 可以直接走 Canvas/SurfaceView桌面端走 Compose Desktop 的 Canvas 是省力路线。音频子弹射击声、爆炸声、背景音乐不同平台播放 API 完全不同。存档本地文件路径、SharedPreferences、数据库各端都有自己的偏好。这四个部分如果要强行统一会出现一个很尴尬的结果公共接口越抽象底层要做的适配反而越多。比如声音播放为了在公共层提供一个playShootSound()你需要在 Android 上接 MediaPlayer在桌面端接 Java Sound在 iOS 上接 AVFoundation本质上只是把“平台差异”从一个地方挪到另一个地方。更务实的做法是核心玩法通过一个GamePlatformBridge接口暴露给平台层调用平台层自己决定实现方式。这样公共代码只依赖一个很小的接口面平台层做起来也不会被公共接口卡死。判断标准打开一个类如果它里面一半以上代码和 Android API 绑定又没有主动抽取数据模型那它就应该留在平台层不要塞进 commonMain。2. 搭建 KMP 工程模块拆分才是移植的骨架KMP 移植失败的案例里大多数不是因为 Kotlin 代码写不出来而是从一开始模块就分得不对。把所有代码放一个模块跑起来才发现 Android 能编过、桌面端某个类找不到最后只能在文件名后面加expect和actual改到怀疑人生。2.1 推荐按“commonMain platformMain”组织而不是按页面组织比较适合这种小游戏的工程结构是StarCommando/ ├── shared/ │ ├── src/commonMain/kotlin/ │ │ ├── core/ │ │ ├── entities/ │ │ ├── systems/ │ │ └── bridge/ │ ├── src/androidMain/kotlin/ │ ├── src/desktopMain/kotlin/ │ └── src/iosMain/kotlin/ ├── androidApp/ ├── desktopApp/ └── iosApp/shared模块承载可复用代码。androidApp、desktopApp、iosApp都是独立的应用壳负责创建窗口、启动游戏循环、把输入交给shared、把shared返回的渲染指令画到屏幕上。游戏逻辑在commonMain平台壳在各自模块这个边界一旦定下来后面加新平台就不会把原来的核心代码搅乱。比如以后要上 Web只需要新建一个webApp公共层基本不用动。2.2 Gradle 配置要注意 target 和依赖版本一致KMP 的构建配置不会特别复杂但有几个点容易踩每个 target 都有自己的 source set新增 target 时要仔细核对依赖在不在对应 source set 里。公共依赖统一用 commonMain 下的api或implementation平台依赖放到各自的 source set。JDK 版本、Android minSdk 和 Kotlin 版本之间的兼容关系要先确认。如果是 Android 项目转 KMP比较省事的路径是新建一个shared模块把原先的单模块工程拆成“壳工程 共享模块”而不是直接在原 Android 工程上强行加入 iOS target。后者很容易让 Gradle 配置和历史代码互相干扰。kotlin { androidTarget { compilerOptions { jvmTarget.set(JvmTarget.JVM_17) } } jvm(desktop) // 如果要用 iOS target在 mac 上才能配置这里 }如果你的机器是 Windows只做 Android 和桌面端可以。iOS target 在 Windows 上没法完整编译这是 Kotlin/Native 的客观限制不是配置错了。2.3 独立出一个GameLoop抽象是移植成败的关键“星球突击队”这类游戏每一帧都要更新位置、判定碰撞、更新 UI。不同端处理帧循环的方式不同Android 有 Choreographer桌面端可以自己开线程循环iOS 有 CADisplayLink。建议在 commonMain 里定义一个时间驱动接口interface GameLoopHost { fun start(onFrame: (deltaSeconds: Float) - Unit) fun stop() }平台各自实现这个接口Android 用 Choreographer桌面端用线程 Thread.sleepiOS 用CADisplayLink。公共层只关心“每帧给我多少时间增量”不关心帧调度的底层机制。这句话看起来简单但它决定了公共代码能不能测试、能不能在无头环境跑逻辑仿真、能不能快速统一逻辑。很多 KMP 游戏项目后期卡住就是因为公共层直接依赖了某个平台的帧回调结果换一个平台就得重构一遍。3. 核心玩法下沉到 commonMain实体、碰撞和状态机这一节是整篇文章最像“写游戏代码”的部分。核心目标只有一个让“星球突击队”的玩法逻辑在 Android、桌面端跑出来完全一致。3.1 实体模型先设计成纯数据类飞船、敌人、子弹都可以用纯数据类表达。不要掺平台类型进去。data class Position( val x: Float, val y: Float ) data class Entity( val id: Int, val position: Position, val velocity: Position, val health: Int, val radius: Float, val kind: EntityKind ) enum class EntityKind { PlayerShip, EnemyShip, Bullet, Explosion }这里的Entity可以在 UI 层直接用来绘制也可以在测试里直接构造一个复杂场景。字符串、数值、枚举都是跨端通用的用它作为公共层的数据契约最安全。3.2 碰撞判定要可复现不要依赖屏幕尺寸“星球突击队”里最容易出现平台差异的是碰撞判定。如果子弹发射位置直接由触摸点的像素坐标决定那不同分辨率下手感会完全不同。更合适的方式是把碰撞和坐标统一在一个“逻辑坐标空间”里渲染层负责把逻辑坐标映射到屏幕坐标。比如把游戏世界固定成 960x540 的逻辑区域所有实体、碰撞都在这个空间里计算。Android 屏幕大就等比例放大桌面窗口小就缩小。这样玩家的操作体验不会因为屏幕尺寸变化而崩坏。碰撞判定的写法也不需要引入复杂的物理引擎圆形碰撞就够fun areColliding(a: Entity, b: Entity): Boolean { val dx a.position.x - b.position.x val dy a.position.y - b.position.y val distanceSquared dx * dx dy * dy val radiusSum a.radius b.radius return distanceSquared radiusSum * radiusSum }判断标准是同一批输入、同一个随机种子在 Android 和桌面端跑出来的得分和过关情况要一致。如果出现两边结果不同优先检查是不是把屏幕像素坐标直接当逻辑坐标用了。3.3 状态机用 sealed class 表达比用 Int 标志位清晰游戏状态一般包括 Ready、Playing、Paused、GameOver、LevelCompleted。用枚举或者 sealed class 比用一堆isPlaying、isPaused、isGameOver布尔变量可靠得多。sealed interface GameStatus { data object Ready : GameStatus data object Playing : GameStatus data object Paused : GameStatus data class GameOver(val score: Int) : GameStatus data class LevelCompleted(val level: Int, val score: Int) : GameStatus }每次状态变化都走同一个入口比如GameController.changeStatus(newStatus)这样切状态时要做的事情比如停止生成敌机、清理场上特效、保存最高分都不会漏。实际测下来状态机做得干净的项目UI 层也轻松。UI 只要观察状态变化就能决定显示“开始按钮”还是“结算面板”不用自己拼一堆判断。3.4 用“时间增量”驱动更新而不是用帧数驱动这里的核心问题是不同设备帧率不一样。60FPS 的机器和 120FPS 的机器如果每次更新都固定移动 1 像素那 120FPS 的飞船速度会快一倍。正确做法是每帧都接收一个deltaSeconds位移和速度都乘上它。fun update(deltaSeconds: Float) { player.moveBy( player.velocity.x * deltaSeconds, player.velocity.y * deltaSeconds ) bullets.forEach { bullet - bullet.moveBy( bullet.velocity.x * deltaSeconds, bullet.velocity.y * deltaSeconds ) } }这样在不同刷新率下角色移动每秒走过的逻辑距离基本一致。移植到桌面端后哪怕显示器的刷新率变成 144Hz也不会出现游戏速度突然变快的问题。4. 平台接口抽象输入、渲染、音效和存档这样设计才不乱把游戏逻辑搬进 commonMain 只是第一步。真正让 KMP 项目变得“能落地”的是一组干净的平台接口。接口定得不好后面接入 iOS 或 Web 时common 代码会被迫跟着改。4.1 输入层公共层只接收“意图”不接收底层按键类型不要直接在公共层写when (keyCode)这样的逻辑因为 Android 的KeyEvent.KEYCODE_SPACE和桌面端的空格键代码不是一套东西。更好的设计是在平台层把驱动数据转成统一的输入事件sealed interface InputEvent { data object MoveLeft : InputEvent data object MoveRight : InputEvent data object FirePressed : InputEvent data object FireReleased : InputEvent data object PausePressed : InputEvent }Android 代码负责把触摸位置换算成 MoveLeft/MoveRight桌面端负责把键盘按键映射成这些事件。公共层的游戏控制器只处理这些事件。这样不仅跨端方便测试也方便。写单元测试时可以直接往控制器里灌一串输入事件然后断言飞船位置是否变化、子弹是否发射。4.2 渲染层公共层输出绘制指令平台层执行绘制对“星球突击队”这种 2D 游戏来说公共层不必直接操作平台 Canvas。可以先在 commonMain 里定义一组绘制指令sealed interface DrawCommand { data class DrawSprite(val textureId: String, val position: Position, val scale: Float) : DrawCommand data class DrawRect(val start: Position, val width: Float, val height: Float, val color: Int) : DrawCommand data class DrawText(val text: String, val position: Position, val size: Float, val color: Int) : DrawCommand }平台层拿到这组指令后按自己的渲染 API 画出来。Android 可以画到 Canvas桌面端可以画到 Swing 或 Compose Desktop 的 Canvas 上。公共层不关心具体怎么画只负责生成当前帧要画什么。这么做有两层好处。第一如果以后要截图、录屏、做回放可以复用同一套指令。第二无头环境下做逻辑测试时只需要忽略指令列表不用真的去跑渲染。4.3 音效层接口可以磨小一点音频的跨平台统一代价很高。建议公共层只定义这些方法playShoot()playExplosion()playPowerUp()stopBgm()startBgm()平台层负责实现。接口越小Android 和桌面端接入时越不会冗余。假如把音量、音调、混音策略都提到公共层那每个平台都要重新实现一遍音效引擎属于过度设计。实测经验音效文件先放在各自平台能访问的目录。Android 放 res/raw桌面端放在资源目录。公共层不要假设文件路径一样。4.4 存档层尽量用公共层定义数据模型平台层只做序列化和持久化最高分、解锁状态、音效开关这些数据可以在 commonMain 里定义成纯数据类data class SaveData( val highScore: Long, val unlockedLevel: Int, val soundEnabled: Boolean )然后定义一个接口interface DataStoreBridge { fun load(): SaveData fun save(data: SaveData) }Android 可以用 SharedPreferences 或 DataStore桌面端可以用本地文件iOS 可以用 NSUserDefaults。但序列化格式尽量用 JSON 等通用格式不要用平台强耦合的序列化方案。这样移植到新平台时公共层不需要改只要新平台实现一个DataStoreBridge就可以了。5. Android 和桌面端的接入流程按“单任务跑通”再“批量验证”KMP 改造不能一上来就在所有 target 上同步跑会把编译错误和逻辑错误混在一起排错难度成倍上升。我更建议把接入流程拆成三个批次。5.1 第一批只跑 Android 单机任务先把核心逻辑抽到 commonMain然后让 Android 的原本界面继续工作。这个阶段不要急着做桌面端先验证一件事原来能玩的玩法现在通过共享逻辑后还能不能玩。需要检查的点游戏启动、暂停、结束是否正常切换触摸输入是否和公共层事件正确对接最高分是否还能正常保存旧存档数据能不能被新结构读取如果 Android 单独跑都不稳就不要继续往下接桌面端。问题出在公共抽象层而不是平台。5.2 第二批桌面端最小 Demo验证 GameLoop 和渲染桥Android 没问题后再建一个 desktopApp先跑一个最小 Demo显示画面、接收键盘输入、执行 30 秒玩法不需要完整实现所有音效和存档。桌面端最容易出现的问题帧循环里Thread.sleep时间不准导致逻辑速度不稳定桌面端没有约束屏幕宽高比碰撞区域被拉伸字体渲染宽度不同导致文本位置偏移这一批只要能证明“同一套 GameCore 在桌面端也能跑起来”就行。5.3 第三批补全平台功能和批量回归桌面端最小 Demo 通过后再把音效、存档、设置项、舞台切换这些补齐。最后做一轮回归测试测试项Android 结果桌面端结果第 1 关 60 秒玩法跑通跑通碰撞判定随机种子一致性一致一致暂停恢复正常正常最高分保存正常正常音频切换正常正常连续 10 局无崩溃通过通过这里说的回归不是人工玩 10 遍而是把游戏逻辑做成可重复运行的自动化测试。比如给定固定输入序列跑完整局断言最终得分和状态一致。这一步能快速发现平台差异而不是靠肉眼去测。6. 移植中常见的异常、卡顿和兼容性问题排查链路KMP 项目的问题排查比单平台项目多一个维度同一个报错可能是公共代码问题、平台实现问题、构建配置问题三者交叉出现。建议遇到问题先按下面的顺序走一遍不要直接改代码。6.1 编译失败先确认 source set 和依赖配置KMP 编译失败最常见的情况是某个依赖只在 commonMain 声明没有在目标 source set 里生效使用了不支持当前 target 的库expect函数声明了但没有把actual放到正确的平台 source setJDK 版本和 Kotlin/Native 要求不一致排查顺序先看错误信息里的文件路径在哪个 source set再看那一行用到的是不是平台特有 API。如果actual缺失Kotlin 通常会在编译期直接提示不用猜。部分版本更新后会有deprecated警告但并不等于马上不能跑。建议先保持依赖版本稳定不要一边做功能迁移一边升级大版本风险会堆叠。6.2 真机运行卡顿先分帧循环和 GC 问题移植到桌面端后出现卡顿首先要明确卡在哪。用性能工具看的时候我会先看三件事deltaSeconds是否突然变大说明帧循环被阻塞绘制指令数量是否异常比如每一帧都创建大量新对象平台层是否做了耗时操作比如在 UI 线程读文件、解压资源“星球突击队”这种小游戏每帧创建几万个实体肯定不现实。建议在公共层限制实体数量上限比如同时最多 200 个包超出时先清理离场特效再决定生成新的敌人。还有一种常见卡顿是桌面端窗口收到鼠标移动事件时触发大量重绘但游戏逻辑没变。这种情况下要限制渲染频率让它和帧循环对齐不要每次都因为系统事件触发重绘。6.3 两边手感不一致先检查逻辑坐标和输入滞后如果 Android 和桌面端玩起来明显不同最常见原因是输入事件没有用统一的时间基准。触摸事件的timestamp和桌面端键盘事件的到达时间不同如果在平台层直接处理会造成延迟差异。建议在公共层用一个统一的“最近输入状态”缓冲每个输入事件只更新状态不立即驱动移动帧循环开始时读取缓冲的输入结合deltaSeconds统一计算。这样两端的输入延迟差异会被压缩到很小。还有一点要注意Android 的触摸事件频率和桌面端鼠标事件频率不同。公共层的MoveLeft和MoveRight事件要设计成“按下持续状态”而不是“每收到一个事件就移动一段固定距离”。6.4 输出结果不一致优先查随机数和浮点精度如果自动化测试里 Android 和桌面端的最终得分不一致第一怀疑对象是随机数生成器。不同平台如果直接使用各自的随机数 API生成的序列会不一样。建议公共层使用一个自定义随机数生成器种子固定这样每局回放可以复现。kotlin.random.Random在 Kotlin 版本相同的情况下大概率行为一致但为了保险游戏关键逻辑还是建议用自己实现的种子随机器。浮点精度问题也不能忽略。Float在 Android 和桌面端都遵循 IEEE 754大多数情况下一致。但如果用Double做了大量累积计算不同平台相近但不等价也可能导致结果漂移。这里最稳妥的做法是所有逻辑坐标和速度都用同一个数值类型不要混用Float和Double。7. 如果后面要接 iOS、Web 或其他平台保留哪些扩展点移植不一定只做一次。工程经验丰富以后你会发现 KMP 项目真正的价值是给未来新平台留出通道。所以“星球突击队”这个项目里哪些地方原本就适合扩展需要提前看清楚。7.1 公共模块内部要保留可替换的实现点游戏规则通常会不断改敌人难度曲线、道具概率、计分方式。这些不要写死在GameScene一个类里。可以抽成接口比如EnemyWaveGenerator控制敌人生成节奏ScoreCalculator控制计分规则PowerUpDropPolicy控制道具掉落概率KMP 移植的公共代码如果做得太具体后续加新平台时反而更难维护。因为新平台不只面临移植问题还要跟着游戏迭代改公共代码。建议至少做到关卡规则能用配置数据描述而不是埋在代码里。这样后续加平台时不需要重新翻译一遍规则。7.2 平台接入时保持“桥接口”数量少而稳定桥接口是公共层和平台层之间的约定比如GameLoopHost、DrawCommandRenderer、DataStoreBridge。这些接口尽量设计成小接口方法数量控制在 5 个以内。如果接口方法太多新平台要实现的 boilerplate 就越多移植热情会迅速下降。写得窄反而好每个接口只做一件事平台层实现时不容易出错。在“星球突击队”里我把输入处理拆成了InputMapper和GameInputReceiver两部分。平台层只负责把原始按键映射成InputEvent公共层负责消费事件。这样 iOS 如果想接入只需要写一段很薄的映射代码公共部分完全不用动。7.3 公共层要能脱离 UI 单独测试“KMP 项目能不能测试”是判断移植质量的一个重要标准。如果游戏逻辑无法在无 UI 环境下运行那后面每个平台修 bug 都要开模拟器成本非常高。我建议给 GameCore 写一个无头测试Test fun fixed seed replay should reach same score() { val game createGame(seed 42L) val input loadFixedInput(case_level1.txt) game.runWithInput(input) assertEquals(15000L, game.currentScore) }这种测试通过后你才敢说“同一套逻辑在所有平台结果一致”。否则只能靠手测覆盖范围很难保证。7.4 别忘了给设计师留出调参入口游戏项目的“参数”不只是技术参数还包含手感参数。比如飞船移动速度、敌方切换方向间隔、道具掉落概率、连击判定时间。这些参数如果散落在代码里每次调手感都要改代码重新编译移植到多个平台后更是折磨。比较推荐的做法是定义一份参数表data class GameplayConfig( val playerSpeed: Float 400f, val bulletCooldown: Float 0.2f, val enemySpawnInterval: Float 1.5f, val comboWindow: Float 2.0f, val maxEntityCount: Int 200 )公共代码只从GameplayConfig读取数值不直接写死。这样平台层还可以根据屏幕方向、设备性能动态调整参数不用动核心逻辑。8. 移植完成后的验收清单和后续维护建议移植完成不是“能编译、能跑”就算数。我最后会按一套验收清单过一遍防止后期在某个平台上突然崩掉。8.1 检查清单[ ] Android 和桌面端都使用同一份 GameCore编译产物里没有复制两份逻辑[ ] 横竖屏切换后逻辑坐标和渲染坐标的映射仍然正确[ ] 游戏暂停后帧循环会停止消耗 CPU而不是继续空转[ ] 最高分保存后重启应用还能读取[ ] 连续 20 局随机种子测试得分一致[ ] 音效开关在两端都生效且不互相影响[ ] 在低端 Android 机上降低实体数量上限后游戏速度保持稳定[ ] 桌面端窗口缩放时渲染不会拉伸变形8.2 维护建议KMP 项目一旦进入长期迭代最怕的就是公共层代码逐渐变得“Android 风格化”。新功能做久了容易把只有 Android 才有的 API 引入 commonMain让其他平台编译器报错。建议每次提交都对四个目标做一遍编译检查./gradlew :shared:compileDebugKotlinAndroid ./gradlew :shared:compileKotlinDesktop能快速发现公共层是否悄悄混入了平台依赖。另外公共模块的 API 要尽量早稳定下来。如果发现自己每天都在改GameController的构造函数说明接口设计还不对。这时候先停下功能开发把桥接口的职责理清楚再继续往下走会更省时间。8.3 最后留一句实在话“星球突击队”这个项目的 KMP 移植真正的难度不在 Kotlin 语法也不在 Gradle 配置而在你怎么忍住不想让所有东西都跨端共享。界面、音频播放、本地文件系统这些平台差异大的部分硬统一不如留接口而玩法规则、碰撞判定、状态机这些业务核心能共享的尽量共享这才是 KMP 最有价值的地方。如果只是学习按“commonMain 游戏核心 Android 壳 桌面壳”这条路跑通一个最小 Demo 就够了。如果要长期量产再用我上面说的这批桥接口和自动化测试把多平台回归的问题掐在早期。