Phaser 3.18.1 输入系统时间同步修复深度解析从InputManager.preRender到KeyboardPlugin.checkDown【免费下载链接】phaserPhaser is a fun, free and fast 2D game framework for making HTML5 games for desktop and mobile web browsers, supporting Canvas and WebGL rendering.项目地址: https://gitcode.com/gh_mirrors/ph/phaser导读Phaser 3.18.1代号 Raphtalia2019 年 6 月 20 日发布是一个聚焦输入系统稳定性修复的小版本核心解决了两处与时间同步相关的缺陷InputManager.preRender未正确取得帧时间以及KeyboardPlugin.time取值错误导致checkDown持续失效。本文以 CHANGELOG-v3.18.1.md 为骨架结合当前仓库源码逐行剖析这两处 Bug 的成因、修复机制与影响范围帮助你理解 Phaser 输入系统在渲染循环中的时间传递链路并掌握checkDown的正确用法。一、版本背景紧随 3.18.0 大版本之后的修复版本3.18.0 在一天前2019 年 6 月 19 日发布对输入系统做了大量改动引入了鼠标滚轮事件POINTER_WHEEL、GAMEOBJECT_WHEEL、按钮释放检测Pointer.leftButtonReleased等以及新的内部方法InputManager.onMouseWheel、processWheelEvent详见 3.18.0 变更日志。其中preRender这个内部更新方法正是在 3.18.0 中引入的源码标注since 3.18.0。3.18.1 没有新增功能仅包含两项 Bug Fix全部集中在输入系统的时间属性传递上。这类紧跟大版本的修复版本在 Phaser 的版本节奏中很常见——大版本重构输入管线后紧接着的小版本用于快速修正重构引入的回归问题。二、修复点一InputManager.preRender未正确取得time属性2.1 变更日志原文InputManager.preRenderdidnt get thetimeproperty correctly, causing input plugin methods that relied on it to fail.2.2 底层机制preRender是每帧输入更新的起点在 src/input/InputManager.js 中preRender是 Input Manager 的核心内部更新方法它在 Game Step 每帧渲染开始前被调用在构造函数中通过GameEvents.PRE_RENDER事件绑定见 src/input/InputManager.js#L322preRender: function () { var time this.game.loop.now; var delta this.game.loop.delta; var scenes this.game.scene.getScenes(true, true); this.time time; this.events.emit(Events.MANAGER_UPDATE); for (var i 0; i scenes.length; i) { var scene scenes[i]; if (scene.sys.input scene.sys.input.updatePoll(time, delta) this.globalTopOnly) { // If the Scene returns true, it means it captured some input that no other Scene should get, so we bail out return; } } },这段源码揭示了三层关键信息时间来源time取自this.game.loop.now即游戏主循环当前帧的时间戳随后写入this.time time。InputManager.time属性src/input/InputManager.js#L227-L236的文档注释明确写着The time this Input Manager was last updated. This value is populated by the Game Step each frame.——它正是由每帧的 Game Step 填充的最后更新时间。输入轮询的入口preRender通过scene.sys.input.updatePoll(time, delta)将时间与增量下发给每个可见 Scene 的输入插件所有依赖时间的输入逻辑命中检测、事件分发都以这个时间戳为基准。全局独占语义当某个 Scene 的updatePoll返回true且globalTopOnly开启时后续 Scene 不再接收本次输入体现了全局最顶层输入独占的设计。2.3 Bug 的成因与影响3.18.1 修复的正是preRender中这一时间取值/赋值环节的缺陷。当InputManager.time无法被正确填充时所有依赖该属性的输入插件方法都会拿到错误的时间基准。InputManager.time作为一个readonly的内部状态被下游多个插件共享包括下一节要讲的 Keyboard 插件一旦源头出错影响会沿着调用链层层放大——这正是一个典型的时间同步回归问题。三、修复点二KeyboardPlugin.time取值错误导致checkDown持续失败3.1 变更日志原文KeyboardPlugin.timewasnt being set to the correct value, causingcheckDownto fail constantly.3.2 关键事实KeyboardPlugin.time是一个 getter在 src/input/keyboard/KeyboardPlugin.js#L927-L942 中time并不是一个被赋值的普通属性而是一个只读的 getter/** * Internal time value. * * name Phaser.Input.Keyboard.KeyboardPlugin#time * type {number} * private * since 3.11.0 */ time: { get: function () { return this.sceneInputPlugin.manager.time; } }它直接转发到sceneInputPlugin.manager.time——也就是上一节分析过的InputManager.time。因此KeyboardPlugin.time的值完全取决于InputManager.preRender是否正确填充了this.time。这正是两个 Bug Fix 相互关联的根源第一个修复preRender 取 time补上了源头第二个修复KeyboardPlugin.time 取对值才能生效。3.3 影响面checkDown的判定逻辑checkDown方法src/input/keyboard/KeyboardPlugin.js#L705-L722是本次 Bug 的直接受害者checkDown: function (key, duration) { if (duration undefined) { duration 0; } if (this.enabled key.isDown) { var t SnapFloor(this.time - key.timeDown, duration); if (t key._tick) { key._tick t; return true; } } return false; },其判定逻辑基于this.time - key.timeDownthis.time是当前帧时间来自KeyboardPlugin.timegetter最终来自InputManager.timekey.timeDown是按键被按下时记录的时间戳二者相减得到按键已持续按下的时长t再经SnapFloor按duration步进取整只有当新的t大于该键上次放行时的_tick时才返回true。当this.time无法取到正确值时this.time - key.timeDown的差值持续异常t key._tick的判定要么永远不成立checkDown恒返回false即持续失败要么行为完全不可预期。由于duration的语义是每隔多少毫秒允许放行一次时间基准错误会直接破坏节流逻辑表现为按住方向键时角色移动频率完全错乱。3.4 受影响的正确姿势checkDown的实战用法checkDown的典型用途是按住连发但带节流例如按住空格键发射子弹但限制每 100ms 最多发射一次。源码注释src/input/keyboard/KeyboardPlugin.js#L687-L696给出了清晰的语义说明// 在 create 中创建一个 Key 对象 var spaceBar this.input.keyboard.addKey(Phaser.Input.Keyboard.KeyCodes.SPACE); // 在 update 中调用 checkDownduration 为 100 表示每 100ms 放行一次 if (this.input.keyboard.checkDown(spaceBar, 100)) { this.fireBullet(); }使用要点duration默认为0表示只要键处于按下状态且新的一帧到来即返回true当 Keyboard 插件被禁用this.enabled false时checkDown恒返回false这是方法内置的防御逻辑与直接读取key.isDown的区别在于checkDown借助时间节流实现了按帧轮询 间隔放行的组合判定适合处理连续输入场景。四、修复链路总结一次输入时间的全局同步将两个修复点串联起来可以还原出 3.18.1 修复的完整时间传递链路Game Loopthis.game.loop.now │ ▼ InputManager.preRender() ──► this.time time ← 修复点一 │ ├──► scene.sys.input.updatePoll(time, delta) 各 Scene 输入轮询 │ └──► 发出 MANAGER_UPDATE 事件 │ ▼ KeyboardPlugin.timegetter ──► manager.time ← 修复点二 │ ▼ KeyboardPlugin.checkDown() ──► SnapFloor(this.time - key.timeDown, duration)这条链路表明InputManager.time是全局输入时间基准KeyboardPlugin.time只是它的一个转发视图。3.18.1 的修复本质上是正本清源——先让源头preRender正确写入帧时间再让消费方Keyboard 插件通过 getter 正确读取最终使checkDown的时间差判定恢复正常。五、修复验证与影响范围从源码结构看本次修复的关键验证点有两个InputManager.time的填充检查 src/input/InputManager.js#L368-L388 中preRender是否在每帧正确执行this.time time并将time/delta传入updatePollKeyboardPlugin.time的取值检查 src/input/keyboard/KeyboardPlugin.js#L935-L942 的 getter 是否正确转发sceneInputPlugin.manager.time。影响范围凡是依赖输入时间戳的功能都会受到本次修复的惠及包括但不限于——基于checkDown的按键连发、Key对象的按住时长判断、以及各 Scene 输入轮询中基于delta的累计逻辑。对于使用 Phaser 3.18.0 且发现键盘连发逻辑异常checkDown恒为false或触发频率错乱的项目升级到 3.18.1 即可恢复正确行为。结语Phaser 3.18.1 虽只包含两项 Bug Fix却清晰展示了游戏框架中时间同步这一基础设施问题的重要性一个看似不起眼的内部属性取值错误会通过preRender → InputManager.time → KeyboardPlugin.time → checkDown的调用链最终表现为玩家可感知的按键失灵。理解这条链路不仅有助于排查历史版本问题也能让你在自定义输入插件或扩展键盘逻辑时正确选择时间数据源——始终以InputManager.time为每帧时间的唯一权威来源避免自行维护可能失同步的时间戳。【免费下载链接】phaserPhaser is a fun, free and fast 2D game framework for making HTML5 games for desktop and mobile web browsers, supporting Canvas and WebGL rendering.项目地址: https://gitcode.com/gh_mirrors/ph/phaser创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Phaser 3.18.1 输入系统时间同步修复深度解析：从 `InputManager.preRender` 到 `KeyboardPlugin.checkDown`
Phaser 3.18.1 输入系统时间同步修复深度解析从InputManager.preRender到KeyboardPlugin.checkDown【免费下载链接】phaserPhaser is a fun, free and fast 2D game framework for making HTML5 games for desktop and mobile web browsers, supporting Canvas and WebGL rendering.项目地址: https://gitcode.com/gh_mirrors/ph/phaser导读Phaser 3.18.1代号 Raphtalia2019 年 6 月 20 日发布是一个聚焦输入系统稳定性修复的小版本核心解决了两处与时间同步相关的缺陷InputManager.preRender未正确取得帧时间以及KeyboardPlugin.time取值错误导致checkDown持续失效。本文以 CHANGELOG-v3.18.1.md 为骨架结合当前仓库源码逐行剖析这两处 Bug 的成因、修复机制与影响范围帮助你理解 Phaser 输入系统在渲染循环中的时间传递链路并掌握checkDown的正确用法。一、版本背景紧随 3.18.0 大版本之后的修复版本3.18.0 在一天前2019 年 6 月 19 日发布对输入系统做了大量改动引入了鼠标滚轮事件POINTER_WHEEL、GAMEOBJECT_WHEEL、按钮释放检测Pointer.leftButtonReleased等以及新的内部方法InputManager.onMouseWheel、processWheelEvent详见 3.18.0 变更日志。其中preRender这个内部更新方法正是在 3.18.0 中引入的源码标注since 3.18.0。3.18.1 没有新增功能仅包含两项 Bug Fix全部集中在输入系统的时间属性传递上。这类紧跟大版本的修复版本在 Phaser 的版本节奏中很常见——大版本重构输入管线后紧接着的小版本用于快速修正重构引入的回归问题。二、修复点一InputManager.preRender未正确取得time属性2.1 变更日志原文InputManager.preRenderdidnt get thetimeproperty correctly, causing input plugin methods that relied on it to fail.2.2 底层机制preRender是每帧输入更新的起点在 src/input/InputManager.js 中preRender是 Input Manager 的核心内部更新方法它在 Game Step 每帧渲染开始前被调用在构造函数中通过GameEvents.PRE_RENDER事件绑定见 src/input/InputManager.js#L322preRender: function () { var time this.game.loop.now; var delta this.game.loop.delta; var scenes this.game.scene.getScenes(true, true); this.time time; this.events.emit(Events.MANAGER_UPDATE); for (var i 0; i scenes.length; i) { var scene scenes[i]; if (scene.sys.input scene.sys.input.updatePoll(time, delta) this.globalTopOnly) { // If the Scene returns true, it means it captured some input that no other Scene should get, so we bail out return; } } },这段源码揭示了三层关键信息时间来源time取自this.game.loop.now即游戏主循环当前帧的时间戳随后写入this.time time。InputManager.time属性src/input/InputManager.js#L227-L236的文档注释明确写着The time this Input Manager was last updated. This value is populated by the Game Step each frame.——它正是由每帧的 Game Step 填充的最后更新时间。输入轮询的入口preRender通过scene.sys.input.updatePoll(time, delta)将时间与增量下发给每个可见 Scene 的输入插件所有依赖时间的输入逻辑命中检测、事件分发都以这个时间戳为基准。全局独占语义当某个 Scene 的updatePoll返回true且globalTopOnly开启时后续 Scene 不再接收本次输入体现了全局最顶层输入独占的设计。2.3 Bug 的成因与影响3.18.1 修复的正是preRender中这一时间取值/赋值环节的缺陷。当InputManager.time无法被正确填充时所有依赖该属性的输入插件方法都会拿到错误的时间基准。InputManager.time作为一个readonly的内部状态被下游多个插件共享包括下一节要讲的 Keyboard 插件一旦源头出错影响会沿着调用链层层放大——这正是一个典型的时间同步回归问题。三、修复点二KeyboardPlugin.time取值错误导致checkDown持续失败3.1 变更日志原文KeyboardPlugin.timewasnt being set to the correct value, causingcheckDownto fail constantly.3.2 关键事实KeyboardPlugin.time是一个 getter在 src/input/keyboard/KeyboardPlugin.js#L927-L942 中time并不是一个被赋值的普通属性而是一个只读的 getter/** * Internal time value. * * name Phaser.Input.Keyboard.KeyboardPlugin#time * type {number} * private * since 3.11.0 */ time: { get: function () { return this.sceneInputPlugin.manager.time; } }它直接转发到sceneInputPlugin.manager.time——也就是上一节分析过的InputManager.time。因此KeyboardPlugin.time的值完全取决于InputManager.preRender是否正确填充了this.time。这正是两个 Bug Fix 相互关联的根源第一个修复preRender 取 time补上了源头第二个修复KeyboardPlugin.time 取对值才能生效。3.3 影响面checkDown的判定逻辑checkDown方法src/input/keyboard/KeyboardPlugin.js#L705-L722是本次 Bug 的直接受害者checkDown: function (key, duration) { if (duration undefined) { duration 0; } if (this.enabled key.isDown) { var t SnapFloor(this.time - key.timeDown, duration); if (t key._tick) { key._tick t; return true; } } return false; },其判定逻辑基于this.time - key.timeDownthis.time是当前帧时间来自KeyboardPlugin.timegetter最终来自InputManager.timekey.timeDown是按键被按下时记录的时间戳二者相减得到按键已持续按下的时长t再经SnapFloor按duration步进取整只有当新的t大于该键上次放行时的_tick时才返回true。当this.time无法取到正确值时this.time - key.timeDown的差值持续异常t key._tick的判定要么永远不成立checkDown恒返回false即持续失败要么行为完全不可预期。由于duration的语义是每隔多少毫秒允许放行一次时间基准错误会直接破坏节流逻辑表现为按住方向键时角色移动频率完全错乱。3.4 受影响的正确姿势checkDown的实战用法checkDown的典型用途是按住连发但带节流例如按住空格键发射子弹但限制每 100ms 最多发射一次。源码注释src/input/keyboard/KeyboardPlugin.js#L687-L696给出了清晰的语义说明// 在 create 中创建一个 Key 对象 var spaceBar this.input.keyboard.addKey(Phaser.Input.Keyboard.KeyCodes.SPACE); // 在 update 中调用 checkDownduration 为 100 表示每 100ms 放行一次 if (this.input.keyboard.checkDown(spaceBar, 100)) { this.fireBullet(); }使用要点duration默认为0表示只要键处于按下状态且新的一帧到来即返回true当 Keyboard 插件被禁用this.enabled false时checkDown恒返回false这是方法内置的防御逻辑与直接读取key.isDown的区别在于checkDown借助时间节流实现了按帧轮询 间隔放行的组合判定适合处理连续输入场景。四、修复链路总结一次输入时间的全局同步将两个修复点串联起来可以还原出 3.18.1 修复的完整时间传递链路Game Loopthis.game.loop.now │ ▼ InputManager.preRender() ──► this.time time ← 修复点一 │ ├──► scene.sys.input.updatePoll(time, delta) 各 Scene 输入轮询 │ └──► 发出 MANAGER_UPDATE 事件 │ ▼ KeyboardPlugin.timegetter ──► manager.time ← 修复点二 │ ▼ KeyboardPlugin.checkDown() ──► SnapFloor(this.time - key.timeDown, duration)这条链路表明InputManager.time是全局输入时间基准KeyboardPlugin.time只是它的一个转发视图。3.18.1 的修复本质上是正本清源——先让源头preRender正确写入帧时间再让消费方Keyboard 插件通过 getter 正确读取最终使checkDown的时间差判定恢复正常。五、修复验证与影响范围从源码结构看本次修复的关键验证点有两个InputManager.time的填充检查 src/input/InputManager.js#L368-L388 中preRender是否在每帧正确执行this.time time并将time/delta传入updatePollKeyboardPlugin.time的取值检查 src/input/keyboard/KeyboardPlugin.js#L935-L942 的 getter 是否正确转发sceneInputPlugin.manager.time。影响范围凡是依赖输入时间戳的功能都会受到本次修复的惠及包括但不限于——基于checkDown的按键连发、Key对象的按住时长判断、以及各 Scene 输入轮询中基于delta的累计逻辑。对于使用 Phaser 3.18.0 且发现键盘连发逻辑异常checkDown恒为false或触发频率错乱的项目升级到 3.18.1 即可恢复正确行为。结语Phaser 3.18.1 虽只包含两项 Bug Fix却清晰展示了游戏框架中时间同步这一基础设施问题的重要性一个看似不起眼的内部属性取值错误会通过preRender → InputManager.time → KeyboardPlugin.time → checkDown的调用链最终表现为玩家可感知的按键失灵。理解这条链路不仅有助于排查历史版本问题也能让你在自定义输入插件或扩展键盘逻辑时正确选择时间数据源——始终以InputManager.time为每帧时间的唯一权威来源避免自行维护可能失同步的时间戳。【免费下载链接】phaserPhaser is a fun, free and fast 2D game framework for making HTML5 games for desktop and mobile web browsers, supporting Canvas and WebGL rendering.项目地址: https://gitcode.com/gh_mirrors/ph/phaser创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考