Phaser3 API文档大纲-InputPlugin

2019-01-08 周二 by 黄复雄.

说明

这是根据Phaser3 API文档中各类之页面右侧的目录整理的,略作说明,或增加代码示例。可做便览之用。

Phaser 3 API Documentation - Class: InputPlugin

Phaser.Input. InputPlugin

输入插件(InputPlugin)属于一个场景,为场景处理所有输入相关的事件、操作。 在场景中通过this.input接收输入插件。

它直接发送事件。例如监听游戏画布的热点点击(pointerdown)事件:

this.input.on('pointerdown', callback, context);

调用游戏对象的setInteractive方法以开启输入,以发送事件:

var sprite = this.add.sprite(x, y, texture);
sprite.setInteractive();
sprite.on('pointerdown', callback, context);

new InputPlugin(scene)

Extends

Phaser.Events.EventEmitter

Members

activePointer :Phaser.Input.Pointer

当前活动的输入点。

cameras :Phaser.Cameras.Scene2D.CameraManager

指向场景的镜头管理器。

displayList :Phaser.GameObjects.DisplayList

指向场景显示列表。

dragDistanceThreshold :number

判定热点正被拖拽的距离阈值,以像素计。

dragTimeThreshold :number

判定热点正被拖拽的时间阈值,以毫秒计。

enabled :boolean

开启输入,这时输入插件每帧循环更新。

gamepad :Phaser.Input.Gamepad.GamepadPlugin

GamepadPlugin类的实例。也可以通过GameConfig属性设置。

keyboard :Phaser.Input.Keyboard.KeyboardPlugin

KeyboardPlugin类的实例,用以生成Key对象,监听指定的键盘事件。也可以通过GameConfig属性设置。

manager :Phaser.Input.InputManager

指向游戏输入管理器。

mouse :Phaser.Input.Mouse.MouseManager

指向鼠标管理器。只有在游戏Configuration文件中开启鼠标支持后,才能设置本属性。 如果你只是想使用鼠标热点,那么请用mousePointer属性。

mousePointer :Phaser.Input.Pointer

鼠标拥有自己独特的Pointer对象,如果做桌面类游戏,能直接引用到。 如果打算同时支持桌面与触摸设备,这时不要使用本属性,而要用activePointer,它将始终指向最近的交互热点。

pointer1 :Phaser.Input.Pointer

基于触摸的热点(Pointer)对象。 默认undefined,除非你用addPointer添加一个Pointer。 下同,共十个触点。

pointer2 :Phaser.Input.Pointer

pointer3 :Phaser.Input.Pointer

pointer4 :Phaser.Input.Pointer

pointer5 :Phaser.Input.Pointer

pointer6 :Phaser.Input.Pointer

pointer7 :Phaser.Input.Pointer

pointer8 :Phaser.Input.Pointer

pointer9 :Phaser.Input.Pointer

pointer10 :Phaser.Input.Pointer

pollRate :integer

热点检查/轮询频率。单位是毫秒。如果用户已经移动、按下或释放过热点,那么热点一定得到检查。本属性仅仅控制未更新时的检查频率。 如果你希望游戏对象相应于热点持续更新,即使热点本身未动,也要设置本属性。 设为0将持续轮询。设为-1将只根据用户的移动轮询。缺省值是-1。

scene :Phaser.Scene

指向输入插件所负责的场景。

settings :Phaser.Scenes.Settings.Object

指向场景的系统设置。

systems :Phaser.Scenes.Systems

指向场景的系统类。

topOnly :boolean

设为true(默认值)时,输入插件将模仿DOM的行为,只从显示列表最顶层的游戏对象发出事件。 如果设为fals,则将从热点下的所有游戏对象发出事件,而不限于顶层的一个。

x :number

活动热点(ActivePointer)的x坐标,根据摄像头列表中的第一个摄像头计算。 如果你的游戏只有一个非变形摄像头,且未使用多个触点,那么这是唯一可安全使用的。

y :number

活动热点(ActivePointer)的y坐标,根据摄像头列表中的第一个摄像头计算。 如果你的游戏只有一个非变形摄像头,且未使用多个触点,那么这是唯一可安全使用的。

Methods

addDownCallback(callback [, isOnce])

添加回调函数,预备收到原生DOM的mousedowntouchstart事件时激发。 通过设置isOnce参数,可以控制回调函数仅调用一次,还是每次事件都调用。

回调函数传递给此方法后,在DOM事件处理器范围内,一发生DOM事件就会马上激发。 因此从浏览器视角来说,他们把看做是“原生的”。 这意味着它们可用于诸如打开新的浏览器窗口,或者任何明确要求用户输入从能激发的各种任务。 不过,这样一来它们导致一些危险,因此不能用于一般的游戏输入,而是给特点情形备用的。

如果你只是想在一个热点落下时执行一个回调函数,那么请换用内置的输入事件系统。

务必请明了,这些回调函数将在浏览器自认为必要时激发。 这可能完全超出了Phaser游戏循环的事件流。 因此,在这些回调函数中,你绝对要使Phaser相关的操作减到最少。 比如,不要销毁游戏对象、更改场景或操作内部系统,否则你很可能生成[海森堡bug(heisenbugs)] (https://en.wikipedia.org/wiki/Heisenbug),这种问题据信是难以重现、无法解决的。

addListener(event, fn [, context])

就指定事件添加监听器。

addMoveCallback(callback [, isOnce])

添加回调函数,预备收到原生DOM的mousemovetouchmove事件时激发。 通过设置isOnce参数,可以控制回调函数仅调用一次,还是每次事件都调用。

其余信息请参考addDownCallback方法。

addPointer( [quantity])

添加新的热点(Pointer)对象到输入管理器中。默认生成两个热点对象: mousePointerpointer1。 可以生成更多,通过调用本方法,或在游戏配置中设置input.activePointers属性,最多可达10个热点。

10个热点通过此方法添加好后,可以通过InputPlugin.pointerX属性获取。

addUpCallback(callback [, isOnce])

添加回调函数,预备收到原生DOM的mouseuptouchend事件时激发。 通过设置isOnce参数,可以控制回调函数仅调用一次,还是每次事件都调用。

其余信息请参考addDownCallback方法。

clear(gameObject)

清空一个游戏对象,使它不再相关联的交互对象。 然后游戏对象排队等待下一次更新时从输入插件中移除。

disable(gameObject)

关闭一个游戏对象的的输入。 关闭输入的游戏对象仍旧持有交互对象组件,还可以重新打开输入,方法是随时传递给InputPlugin.enable方法。

emit(event [, args])

调用给定事件的所有已注册的监听器。

enable(gameObject [, shape] [, callback] [, dropZone])

开启一个游戏对象的互动功能。 如果游戏对象已经有互动对象组件,那么组件将激活并返回。 否则,生成新的互动对象组件,并分配到游戏对象的输入属性中。

输入通过点击区域起作用,一般都用几何形状如方形、圆形,给游戏对象作点击区域。 不过,如果要处理更高级的输入检测,也可以提供你自己的点击区域形状、回调函数。 如果没有提供参数,将尝试基于游戏对象所用的纹理框架生成一个方形点击区域。 如果不是纹理边框对象(如GraphicsBitmapText对象),将无法生成,这时你需要提供指定的形状供它使用。

你也可以提供一个输入配置对象作为唯一参数。

eventNames()

返回一个数组,列出在事件发生器中注册过监听器的所有事件。

hitTestPointer(pointer)

接收一个给定热点,对它执行一个点击测试,看看下面是哪些互动游戏对象。

点击测试针对热点下所有摄像头都予以执行。如果下面是多重镜头,先从镜头列表的最顶层一个检测,如果没有发现,再往下依次重复。

isActive()

检测本插件及其所属场景是否都是活动的。

listenerCount(event)

返回给定事件的监听器数量。

listeners(event)

返回就给定事件所注册的所有监听器。

makePixelPerfect( [alphaTolerance])

生成一个函数,以传递给setInteractive, enablesetHitArea, 它将处理基于ImageSprite的游戏对象上的像素完美(pixel-perfect,完美地基于像素)的输入检测。 如下将生成一个精灵,它的所有透明度大于等于1的所有像素都可点击。

this.add.sprite(x, y, key).setInteractive(this.input.makePixelPerfect());

如下将生成一个精灵,它的有所透明度大于150的像素都可以点击。

this.add.sprite(x, y, key).setInteractive(this.input.makePixelPerfect(150));

一旦你做了一个像素完美的互动对象,将影响它的所有与输入有关的事件:down, up, dragstart, drag, 等等。

因为热点与游戏对象互动时,将持续地对纹理进行轮询,从给定坐标中抽取一个像素,检测他的色值。 这是高消耗的过程,所以应该只在确实需要的游戏对象上才运用。

无法在非纹理基础的游戏对象上实现像素完美效果。所以这无法在Graphic, BitmapText, RenderTexture, Text, Tilemap, ContainerParticle上起效。

off(event, fn, context, once)

移除给定事件的监听器。

on(event, fn [, context])

为给定事件添加监听器。

once(event, fn [, context])

为给定事件添加一次性监听器。

removeAllListeners( [event])

移除所有监听器,或只针对就给定事件。

removeListener(event, fn, context, once)

移除给定事件的所有监听器。

setDefaultCursor(cursor)

通知输入系统设置客户定制光标。这个光标将作为默认光标,用于与游戏画布互动时。

如果互动对象也设置了客户定制光标,那么它用过之后将重置为这里设置的光标。

任何有效的CSS光标值可以,也包括指向图像文件的路径,等等。

`JavaScript this.input.setDefaultCursor('url(assets/cursors/sword.cur), pointer');

请看各浏览器对文件格式、大小的不同支持:

CSS - cursor

Using_URL_values_for_the_cursor_property

由你决定选取合适的光标格式,以便在你需要支持的各浏览器上都起效。

setDraggable(gameObjects [, value])

就给定有序对象数组设置可否拖拽。 可以全设置为可以拖拽,或者传递false值以移除所有许可。 游戏对象指定可拖拽后才会发出拖拽事件。

setGlobalTopOnly(value)

如果设置为true,全局的输入管理器将模仿DOM行为,只从显示列表最顶层的游戏对象发出事件。 如果设置为false,它将从热点下的所有游戏对象发出事件,而不只是最顶层的一个。

setHitArea(gameObjects [, shape] [, callback])

就给定的游戏对象数组设置点击区域。 典型的点击区域是Phaser提供的几何形状,比如Phaser.Geom.RectanglePhaser.Geom.Circle。 不过,也可以是对给定回调函数起效的任何对象。

如果没有提供点击区域,将基于游戏对象的尺寸生成一个方形,如果可以算出的话。

点击区域回调(HitAreaCallback)是一个函数,它接收xy坐标值,根据坐标值是否位于形象的范围内返回一个布尔值。 所有Phaser几何对象都提供这种函数,比如Phaser.Geom.Rectangle.Contains

setHitAreaCircle(gameObjects, x, y, radius [, callback])

就给定游戏对象数组设置点击区域为Phaser.Geom.Circle形状(圆), 使用给定的坐标、半径以控制其位置和大小。

setHitAreaEllipse(gameObjects, x, y, width, height [, callback])

就给定游戏对象数组设置点击区域为Phaser.Geom.Ellipse形状(椭圆), 使用给定的坐标、尺寸以控制其位置和大小。

setHitAreaFromTexture(gameObjects [, callback])

为游戏对象数组设置点击区域为Phaser.Geom.Rectangle形状(方形), 使用游戏对象的纹理边框来界定点击区域的位置和大小。

setHitAreaRectangle(gameObjects, x, y, width, height [, callback])

为游戏对象数组设置点击区域为Phaser.Geom.Rectangle形状(方形), 使用给定的坐标、尺寸以控制其位置和大小。

setHitAreaTriangle(gameObjects, x1, y1, x2, y2, x3, y3 [, callback])

为游戏对象数组设置点击区域为Phaser.Geom.Triangle形状(三角形), 使用给定的坐标、尺寸以控制其位置和大小。

setPollAlways()

设置始终轮询的热点(Pointer)。 轮询一个热点时,运行一次点击测试以观察它下面是哪些游戏对象, 或是哪些对象与它互动,不管热点实际上有没有移动。

如果你希望游戏中的对象发出事件,而对象在持续移动,而热点可能没有动,这时你应该开启本项。 每帧轮询需要额外算力消耗,游戏中有大量互动对象时尤其如此。

setPollOnMove()

设置移动或更新时只轮询的某些热点。 轮询一个热点时,运行一次点击测试以观察它下面是哪些游戏对象, 或是哪些对象与它互动。

setPollRate(value)

设置轮询速率。即再次轮询热点时已经过去的时间。 请看setPollAlwayssetPollOnMove方法。

setTopOnly(value)

如果设置为true,输入插件将模仿DOM行为,只从显示列表最顶层的游戏对象发出事件。 如果设置为false,它将从热点下的所有游戏对象发出事件,而不只是最顶层的一个。

sortGameObjects(gameObjects)

给一个游戏对象数组,排序后返回,使游戏对象按深度索引值排序,最低的在最下面。

stopPropagation()

使输入管理器在余下的游戏步骤里,停止发出任何事件。

published from :Phaser 3 API Documentation - Class: InputPlugin


Fork me on GitHub