上一篇写完基础渲染棋盘网格和方块图形总算能显示出来了。当时我以为整个项目最难的环节已经过去结果把工程部署到开发板上、拿起遥控器按下方向键、界面上的方块纹丝不动的那一刻我才意识到对于Flutter for OpenHarmony这种“API大体兼容、细节处处不同”的适配分支来说交互控制与事件处理才是真正的深水区。这篇是系列第三篇专门讲俄罗斯方块的交互控制与事件处理。核心解决三件事键盘事件为什么收不到、收到之后怎么变成方块动作、动作触发后如何与碰撞检测形成闭环。适合已经在OpenHarmony上跑通Flutter渲染的开发者也适合准备做遥控器、手柄、实体键盘这类重交互应用的团队参考。文章里的代码都是我在项目里实际跑过的拿来改改就能用。1. 让按键事件先到达游戏页面焦点与键值适配1.1 事件“丢”在了哪里一闪而过的焦点问题先说我遇到的第一个诡异问题。模拟器上一切正常方向键按下去方块老老实实移动。换到OpenHarmony开发板上按键完全无响应log里一点打印都没有。排查了一圈问题出在焦点Focus上。Flutter的键盘事件分发机制和触摸事件不一样触摸事件从GestureBinding往下分发任何Widget都能通过GestureDetector收到但键盘事件必须先从FocusManager找到当前持有焦点的节点再把事件派发给这个节点及它的祖先节点。如果游戏页面压根没有持有焦点那按键事件就像敲在隔壁房间的门上你在屋里什么也听不见。这个“夺舍”最容易发生在两种场景。一种是你调试的时候在页面上放了一个TextField控制台你往里敲过指令之后焦点就留在TextField上再按方向键全部进了文本输入框。另一种是路由切换从设置页回到游戏页时Flutter并不保证路由自动把焦点交还给新页面焦点可能已经悬空了。解决办法是在游戏页面初始化后主动申请焦点class _GamePageState extends StateGamePage with SingleTickerProviderStateMixin { final FocusNode _gameFocusNode FocusNode(); override void initState() { super.initState(); WidgetsBinding.instance.addPostFrameCallback((_) { _gameFocusNode.requestFocus(); }); } override Widget build(BuildContext context) { return Focus( focusNode: _gameFocusNode, autofocus: true, onKeyEvent: _handleKeyEvent, child: _buildGameBoard(), ); } }autofocus: true在页面第一次构建时就能拿到焦点addPostFrameCallback里的requestFocus则是应对路由切换后焦点丢失的兜底。两者一起上基本能覆盖绝大多数场景。1.2 用Focus监听而不是RawKeyboardFlutter接入键盘事件有两条路Focus.onKeyEvent和HardwareKeyboard.instance.addHandler。很多人图省事用后者因为它不需要关心焦点全局都能收到。但我在项目里强烈建议你抛弃这个“快捷键”老老实实用Focus。原因有二。第一Global handler收到的事件不会经过焦点链路的过滤你会收到大量跟游戏无关的按键比如系统按键、音量键每一条都要自己去判断要不要响应。第二同一帧内一个按键事件可能在Global handler里被回调多次比如长按触发repeat事件时HardwareKeyboard会先派发keyDown再派发repeat你自己做状态机很容易把逻辑搞乱。Focus的onKeyEvent回调长这样KeyEventResult _handleKeyEvent(FocusNode node, KeyEvent event) { if (event is! KeyDownEvent) { return KeyEventResult.ignored; } if (event.logicalKey LogicalKeyboardKey.arrowLeft) { _controller.startMove(Direction.left); return KeyEventResult.handled; } if (event.logicalKey LogicalKeyboardKey.arrowRight) { _controller.startMove(Direction.right); return KeyEventResult.handled; } return KeyEventResult.ignored; }注意几点。第一KeyEvent有KeyDownEvent、KeyUpEvent、KeyRepeatEvent三种子类你要明确区分。我只在KeyDownEvent时触发动作为起始在KeyUpEvent时通知控制器停止连发repeat事件则由控制器内部的计时器自行处理不依赖系统按键重复。第二处理完的事件一定要返回KeyEventResult.handled否则Flutter会继续向上冒泡可能导致同一个按键触发了页面上的其他交互组件。1.3 键值归一化不要依赖底层keyCode数值在标准Flutter里event.logicalKey和event.physicalKey分别代表逻辑键和物理键。逻辑键不随键盘布局变化适合判断功能物理键表示键盘上的物理位置适合做键位绑定配置。判断上下左右用LogicalKeyboardKey.arrowLeft这类逻辑键就够。但Flutter for OpenHarmony在这里有个隐藏坑OpenHarmony的设备五花八门电视盒子上的遥控器、开发板外接的USB键盘、带按键的平板底座它们上报的原始键值跟标准键盘差异很大。Dart层虽然尽力把底层键值归一化成LogicalKeyboardKey但远没有做到100%覆盖。我自己碰到过的是遥控器的“确认键”在标准Flutter里是arrowDown在某台设备上却上报成了enter。游戏里要做菜单确认和方向下移两个功能结果这两个键混在一起了。所以键值处理建议做成一层独立映射不要散落在业务代码里class GameKeyMapper { static Direction? keyToMoveDirection(LogicalKeyboardKey key) { if (key LogicalKeyboardKey.arrowLeft) return Direction.left; if (key LogicalKeyboardKey.arrowRight) return Direction.right; if (key LogicalKeyboardKey.arrowDown) return Direction.down; if (key LogicalKeyboardKey.arrowUp) return Direction.up; return null; } static bool isActionKey(LogicalKeyboardKey key) { return key LogicalKeyboardKey.enter || key LogicalKeyboardKey.space; } }然后写一个适配层把真机上打印出来的异常键值映射成标准逻辑键。真机上打印event.logicalKey.debugName几秒钟就能把设备的键值字典摸清楚。这里切记一点永远不要在业务代码里直接跟底层keyCode数值比较OpenHarmony各机型上报的数值并不统一今天能用明天换个盒子可能就废了。2. 游戏循环与输入指令队列别让按键直接操作棋盘2.1 为什么按下键不能立刻改坐标我见过不少俄罗斯方块的实现直接在事件处理里做position.x 1再setState一下。这种做法在网页版能跑在Flutter for OpenHarmony上会暴露两个严重问题。第一个问题输入事件在UI isolate里触发跟渲染帧并不是严格同步的。如果你的按键是在两次渲染之间被处理的方块会在画面中间突然跳一下连续快速按键时还会出现一帧移动两格、下一帧不动的情况视觉上就是“抖动”。第二个问题直接在事件回调里改游戏状态意味着碰撞检测、落定判定、消行逻辑全部要在这个回调里同步执行。一套完整的交互状态机摊开在事件回调里代码会迅速变成一团乱麻。正确的做法是事件回调只负责把“意图”记录到一个指令队列里游戏循环每帧消费这个队列统一更新逻辑状态最后再触发渲染。2.2 游戏循环的两种方案对比我拿Timer.periodic跑了第一版第二版换成Ticker体感差异非常明显。两者区别在于精度来源Timer.periodic靠消息循环调度某个时刻系统忙起来回调就可能被推迟几十甚至几百毫秒Ticker跟着vsync信号走频率跟渲染帧率对齐在游戏这类需要跟手操作的场景里更可靠。方案回调时机精度暂停/恢复适用场景Timer.periodic消息循环有空闲时受任务排队影响可能漂移cancel后重建Timer低频逻辑、网络轮询Ticker每帧vsync信号与刷新率同步误差在单帧内ticker.stop / ticker.start游戏逻辑、逐帧动画我的循环结构是Ticker驱动逻辑里用Stopwatch做时间累加class _GamePageState extends StateGamePage with SingleTickerProviderStateMixin { late final Ticker _ticker; final Stopwatch _clock Stopwatch()..start(); Duration _lastTick Duration.zero; void _onTick(Duration elapsed) { final delta elapsed - _lastTick; _lastTick elapsed; _controller.advance(delta.inMilliseconds); } override void initState() { super.initState(); _ticker createTicker(_onTick)..start(); } override void dispose() { _ticker.dispose(); _clock.stop(); super.dispose(); } }_onTick每帧触发一次delta是距离上一帧的时间差单位毫秒。这样游戏循环的步进完全由时间驱动帧率波动不会导致方块加速或减速。2.3 指令队列与同帧去重有了游戏循环事件回调就变得很轻。我的GameController维护了一个指令队列class GameController extends ChangeNotifier { final SetGameAction _queuedActions {}; final MapDirection, bool _pressedDirections { Direction.left: false, Direction.right: false, Direction.down: false, }; void onKeyDown(KeyEvent event) { final action actionFromKey(event.logicalKey); if (action ! null) { _queuedActions.add(action); } } void onKeyUp(KeyEvent event) { final action actionFromKey(event.logicalKey); if (action ! null) { _queuedActions.remove(action); } } void advance(int deltaMs) { if (_queuedActions.contains(GameAction.hardDrop)) { hardDrop(); } if (_queuedActions.contains(GameAction.rotate)) { rotate(); } if (_pressedDirections[Direction.left]!) { moveLeftByRepeat(deltaMs); } // ... gravity accumulation ... } }用Set而不是List放指令队列天然去重。同一帧内按十次左键也只会消费一次移动。事件回调里绝对不直接修改棋盘数据只改“意图集合”游戏循环每帧统一消化。这是整个交互系统最核心的设计思想后面所有跟手性问题都靠这个架构兜底。3. 移动、旋转与加速下落的具体实现3.1 移动与长按连发自己控制重复节奏俄罗斯方块有一个手感上的细节按下方向键之后方块先执行一次移动然后过一小段时间才开始连续移动。这是从红白机时代延续下来的交互惯例。Flutter的KeyRepeatEvent能提供系统级别的重复事件但重复间隔由系统决定在OpenHarmony各设备上表现不一致。我在控制器里自己实现重复逻辑class DirectionalRepeatState { Direction direction; Duration pressedAt; Duration lastMovedAt; static const Duration initialDelay Duration(milliseconds: 250); static const Duration repeatInterval Duration(milliseconds: 50); bool shouldMove(Duration now) { final elapsedSincePress now - pressedAt; if (elapsedSincePress initialDelay) return false; final elapsedSinceMove now - lastMovedAt; return elapsedSinceMove repeatInterval; } }按下方向键时记录pressedAt前250毫秒只响应单次移动之后每50毫秒自动移动一次。这样无论设备自身按键重复快慢游戏里的移动手感完全一致。我当时把这个参数暴露成可配置项实测下来250ms/50ms是大多数人都舒服的组合手速快的可以调成200ms/40ms。3.2 旋转与Wall Kick一套最常用的墙踢序列接下来是旋转。方块旋转本质上是矩阵变换7种方块我用统一的4x4矩阵存储旋转就是矩阵的转置加行反转ListListint rotateMatrixRight(ListListint matrix) { final n matrix.length; final m matrix[0].length; return List.generate(m, (i) { return List.generate(n, (j) matrix[n - 1 - j][i]); }); }如果旋转后的位置发生碰撞不能直接拒绝旋转而要尝试进行位置偏移这就是“墙踢”Wall Kick。比如方块贴着左侧墙壁时按旋转键如果不允许偏移旋转会被直接拒绝手感极其僵硬。我的实现尝试一个标准偏移序列static const Listint kickOffsets [0, -1, 1, -2, 2]; bool tryRotateWithKick() { final originalMatrix currentPiece.matrix; final rotatedMatrix rotateMatrixRight(originalMatrix); for (final xOffset in kickOffsets) { if (canPlaceAt(nextX xOffset, nextY, rotatedMatrix)) { currentPiece.matrix rotatedMatrix; currentPiece.x xOffset; return true; } } // 再尝试向上偏移一格处理贴地旋转的场景 for (final xOffset in kickOffsets) { if (canPlaceAt(nextX xOffset, nextY - 1, rotatedMatrix)) { currentPiece.matrix rotatedMatrix; currentPiece.x xOffset; currentPiece.y - 1; return true; } } return false; }kickOffsets里的0表示原地旋转然后依次尝试左移一格、右移一格、左移两格、右移两格。这套序列覆盖了大部分靠墙旋转的场景。最后那个向上偏移的循环是给贴地旋转准备的否则方块落到底部时贴着地板旋转经常被误判为失败。3.3 软降与硬降两种下落动作的区别软降就是按住下键或按下下方向后方块加速下落。实现上不复杂在重力累加器里把下落间隔乘以一个倍率即可。我用的倍率是20倍也就是正常下落间隔是800毫秒软降时按下键后每40毫秒检查一次是否可下移。硬降则完全不同。硬降要求方块立刻从当前位置掉落到底部中间过程不需要逐格动画。实现方式是预计算落点距离void hardDrop() { int dropDistance 0; while (canPlaceAt(currentPiece.x, currentPiece.y dropDistance 1, currentPiece.matrix)) { dropDistance; } currentPiece.y dropDistance; lockPiece(); score dropDistance * 2; notifyListeners(); }注意这里canPlaceAt里的循环条件必须是从当前y开始一格一格往上递增验证直到下一个位置放不下为止。不要用数学计算去代替逐格验证因为棋盘下方的空洞、凸起会严重影响计算结果逐格验证虽然慢但游戏一次硬降最多20格性能毫无压力。注意硬降后要立刻执行lockPiece和消行判定不能把落定逻辑延后到下一次tick否则玩家快速连按硬降键时方块可能还没锁定就又执行了下一次硬降产生“穿墙”效果。这是我在项目里踩过的真实Bug。4. 碰撞检测与方块落定交互指令的最终校验4.1 棋盘数据结构与方块坐标碰撞检测是整个交互事件的最后一道关卡。所有移动、旋转指令最终都要交给这一层验证验证通过才能修改坐标。我的棋盘模型很简单const int boardRows 20; const int boardCols 10; typedef Board ListListint; class Tetromino { ListListint matrix; int x; int y; }Board里的int是格子状态0表示空非0表示已落定的方块颜色索引。Tetromino.x和Tetromino.y表示方块矩阵左上角在棋盘上的位置。注意这里的关键点方块实际渲染时不一定是矩阵左上角刚好对应棋盘坐标矩阵里可能有很多空的边界格子。4.2 一个canMove判断全部碰撞然后写一个统一的碰撞检测方法处理三种碰撞左右墙壁、底部边界、与其他已落定方块重叠bool canPlaceAt(int x, int y, ListListint matrix) { for (var row 0; row matrix.length; row) { for (var col 0; col matrix[row].length; col) { if (matrix[row][col] 0) continue; final boardX x col; final boardY y row; if (boardX 0 || boardX boardCols) return false; if (boardY boardRows) return false; // 只在地面及以下检查重叠boardY为负代表方块还在顶部未进入棋盘直接放行 if (boardY 0 _board[boardY][boardX] ! 0) { return false; } } } return true; }这个方法我几乎在所有的动作里都调用左移调用canPlaceAt(currentPiece.x - 1, currentPiece.y, matrix)右移调用canPlaceAt(currentPiece.x 1, ...)下落调用canPlaceAt(currentPiece.x, currentPiece.y 1, ...)旋转调用前面说过的tryRotateWithKick。有个新手容易踩的坑boardY 0这个判断不能省略。方块从顶部生成时矩阵上半部分可能还在棋盘外_board[-1]会抛异常或拿到错误数据。一定要在查board之前判断是否已经进入棋盘范围。4.3 落定、消行与事件链闭合当重力逻辑发现canPlaceAt(currentPiece.x, currentPiece.y 1, matrix)返回false说明方块下方没有任何可移动空间执行落定void lockPiece() { for (var row 0; row currentPiece.matrix.length; row) { for (var col 0; col currentPiece.matrix[row].length; col) { if (currentPiece.matrix[row][col] 0) continue; final boardX currentPiece.x col; final boardY currentPiece.y row; if (boardX 0 boardX boardCols boardY 0 boardY boardRows) { _board[boardY][boardX] currentPiece.colorIndex; } } } clearLines(); spawnNextPiece(); notifyListeners(); }落定的格子如果超出棋盘范围怎么办在clearLines()之前先做一次顶部越界检查如果有方块超出顶部直接触发游戏结束。这一层也是防止旋转时墙踢偏移过头导致方块永久卡在棋盘上方。消行逻辑从下往上扫描void clearLines() { for (var row boardRows - 1; row 0; row--) { if (_board[row].every((cell) cell ! 0)) { _board.removeAt(row); _board.insert(0, List.filled(boardCols, 0)); row; // 继续检查这一行因为上面的行被移下来了 lineCount; } } }removeAt加insert(0, ...)是标准做法消掉一行顶部补一行空行。循环里row是为了处理四连消或多行消除的连锁情况因为removeAt之后上方的行下移当前下标需要重新检查一次。4.4 旋转后卡墙的具体场景与验证我在测试时发现一个高频BugI型方块贴左墙时旋转90度后部分格子越过边界墙踢偏移尝试不生效旋转直接被拒绝。这个Bug最隐蔽的地方在于它只发生在方块贴墙的那一侧而且不同方块触发条件不同。用之前的tryRotateWithKick代码就很好排查。贴上左墙时我们先试kickOffsets里的-1也就是向左偏移一格。但向左偏移会撞得更狠所以会被拒绝。接着试1方块向右挪一格刚好避开了墙。这时旋转成功方块会“贴着墙跳出来”。这就是墙踢的意义。提示调试旋转问题时在tryRotateWithKick里把每次尝试的偏移值和碰撞结果打出来你会立刻知道是哪一档偏移起了作用以及哪个偏移条件没满足。这类逻辑用printf式调试比断点高效得多。5. 真机实测与优化模拟器能跑不等于真机跟手5.1 模拟器与开发板的响应差异整个交互链路在模拟器上跑得非常顺滑但部署到OpenHarmony开发板后发现了明显的延迟问题。实测数据模拟器上按键到方块移动的响应时间在5到15毫秒之间肉眼基本无感开发板上则达到20到40毫秒快速连按时偶发50毫秒以上的延迟已经有明显的“不跟手”感觉。排查后发现主要开销不在事件分发而在Dart侧的消息循环被日志输出和垃圾回收拖累。我在调试阶段每个动作都加了debugPrint在开发板上连续按键时大量的日志输出让消息循环严重排队按键处理被延迟。解决方法是把调试日志换成条件编译并加了可视化调试面板const bool debugGameLog bool.fromEnvironment(DEBUG_GAME); void logDebug(String message) { if (debugGameLog) { debugPrint([game] $message); } }用--dart-defineDEBUG_GAMEtrue开启详细日志平时关闭。Release模式下开启和关闭日志的性能差距在开发板上可以达到30%以上这部分优化立竿见影。另外如果你在PC上调试时遇到e/flutter [error:flutter/runtime/dart_vm_initializer.cc(41)] unhandled exception这类框架层日志刷屏别慌这通常只是Dart侧未捕获异常的正常输出重点看它后面的异常堆栈找到你自己的业务代码栈帧而不是把时间花在纠结框架日志上。5.2 触摸屏无键盘场景虚拟方向键OpenHarmony很多设备根本没物理键盘只有触摸屏。这时交互入口要从KeyEvent切换成手势。我的做法是抽象出一个InputProvider接口实体键盘和虚拟按键都实现它abstract class GameInputProvider { void setController(GameController controller); void dispose(); } class KeyboardInputProvider extends GameInputProvider { // 实现Focus onKeyEvent把事件转成controller的onKeyDown/onKeyUp } class TouchInputProvider extends GameInputProvider { // 在虚拟方向键的GestureDetector回调里调用controller的onKeyDown/onKeyUp }虚拟方向键的实现在UI层很简单关键在于把onTapDown和onTapUp分别映射成按下和抬起GestureDetector( onTapDown: (_) _controller.onDirectionDown(Direction.left), onTapUp: (_) _controller.onDirectionUp(Direction.left), onTapCancel: () _controller.onDirectionUp(Direction.left), child: _buildKeyButton(Icons.chevron_left), )长按连续移动逻辑和实体键盘完全共用因为GameController内部的DirectionalRepeatState只关心“这个方向是否处于按下状态”不管它来自键盘还是触摸屏。这块复用帮我省掉了大量重复代码也是我建议你抽象InputProvider的根本原因。5.3 两个典型Bug现场与修复思路第一个Bug从设置页返回游戏页后方向键失灵。原因是路由页面切换后游戏页的FocusNode失去了焦点。修复方案是在路由返回后重新请求焦点或者监听RouteAware的didPopNext事件。我用的是后者因为didPopNext能精确覆盖从子路由返回的所有场景。class _GamePageRouteAware extends RouteAware { final FocusNode focusNode; _GamePageRouteAware(this.focusNode); override void didPopNext() { focusNode.requestFocus(); } }第二个Bug快速连按旋转加左右方向键时方块偶尔出现两个方向同时移动、旋转卡顿的情况。这个Bug的根因是我在旧版代码里用了_queuedActions的List没有去重同一帧里一个事件被重复消费。改成Set后问题消失。另外还有一层就是左移和右移同时按住时我在advance里先处理左移再处理右移导致两个方向互相抵消。这点在方向键处理里注意优先级即可两个方向同时按下时以先按下的方向为准。调试这类交互Bug建议一定在游戏页面放一个输入可视化区域把当前_pressedDirections和_queuedActions实时渲染出来。你会非常直观地看到“我以为我按了左键实际系统上报的是右键”这类键值映射问题比盯着断点猜半天高效太多。实战经验就到这里。游戏循环、指令队列和碰撞检测的架构是这套代码最值得保存的部分后面不管是做俄罗斯方块的五连消变体、倒计时玩法还是把输入换成语音指令都只需要替换InputProvider这一层核心逻辑一行不用动。
