Godot3 API - InputEvent

InputEvent

• Godot3 API - Docs » Inputs » InputEvent

What is it?

Managing input is usually complex, no matter the OS or platform. To ease this a little, a special built-in type is provided, InputEvent. This datatype can be configured to contain several types of input events. Input events travel through the engine and can be received in multiple locations, depending on the purpose.
입력 관리는 OS 나 플랫폼에 관계없이 일반적으로 복잡합니다. 이 작업을 좀 더 쉽게하기 위해 InputEvent라는 특수한 내장 유형이 제공됩니다. 이 데이터 유형은 여러 유형의 입력 이벤트를 포함하도록 구성 될 수 있습니다. 입력 이벤트는 엔진을 통과하며 목적에 따라 여러 위치에서 수신 할 수 있습니다.

Here is a quick example, closing your game if the escape key is hit:
다음은 이스케이프 키가 눌 렸을 때 게임을 닫는 간단한 예입니다:

func _unhandled_input(event):
    if event is InputEventKey:
        if event.pressed and event.scancode == KEY_ESCAPE:
			get_tree().quit()

However, it is cleaner and more flexible to use the provided InputMap feature, which allows you to define input actions and assign them different keys. This way, you can define multiple keys for the same action (e.g. they keyboard escape key and the start button on a gamepad). You can then more easily change this mapping in the project settings without updating your code, and even build a key mapping feature on top of it to allow your game to change the key mapping at runtime!
그러나 입력 동작을 정의하고 다른 키를 할당 할 수 있도록 제공된 InputMap 기능을 사용하는 것이보다 깔끔하고 유연합니다. 이렇게하면 동일한 작업 (예 : 키보드 이스케이프 키 및 게임 패드의 시작 버튼)에 대해 여러 개의 키를 정의 할 수 있습니다. 그런 다음 코드를 업데이트하지 않고도 프로젝트 설정에서이 매핑을보다 쉽게 변경할 수 있으며 런타임에 키 매핑을 변경하도록 키 매핑 기능을 빌드 할 수도 있습니다!

You can setup your InputMap under Project > Project Settings > Input Map and then use those actions like this:
프로젝트> 프로젝트 설정> 입력 맵 에서 InputMap을 설정하고 다음과 같은 작업을 사용할 수 있습니다:

func _process(delta):
    if Input.is_action_pressed("ui_right"):
		# Move right

How does it work?

Every input event is originated from the user/player (though it's possible to generate an InputEvent and feed them back to the engine, which is useful for gestures). The OS object for each platform will read events from the device, then feed them to MainLoop. As SceneTree is the default MainLoop implementation, events are fed to it. Godot provides a function to get the current SceneTree object : get_tree(). 모든 입력 이벤트는 사용자 / 플레이어에서 발생합니다 (InputEvent를 생성하여 엔진에 다시 전달할 수 있으므로 제스처에 유용합니다). 각 플랫폼의 OS 개체는 장치에서 이벤트를 읽은 다음 MainLoop에 이벤트를 제공합니다. SceneTree는 기본 MainLoop 구현이므로 이벤트가 전달됩니다. Godot은 get_tree () 와 같은 현재 SceneTree 객체를 가져 오는 함수를 제공합니다.

But SceneTree does not know what to do with the event, so it will give it to the viewports, starting by the "root" Viewport (the first node of the scene tree). Viewport does quite a lot of stuff with the received input, in order:
하지만 SceneTree는 이벤트를 어떻게 처리해야할지 모르기 때문에 "루트"뷰포트 (장면 트리의 첫 번째 노드)부터 시작하여 뷰포트에 줄 것입니다. 뷰포트는 수신 된 입력을 순서대로 처리합니다.

• First of all, the standard Node._input() function will be called in any node that overrides it (and hasn't disabled input processing with Node.set_process_input()). If any function consumes the event, it can call SceneTree.set_input_as_handled(), and the event will not spread any more. This ensures that you can filter all events of interest, even before the GUI. For gameplay input, Node._unhandled_input() is generally a better fit, because it allows the GUI to intercept the events.
  우선 표준 Node._input () 함수는 Node.set_process_input ()을 사용하여 입력 처리를 비활성화하지 않은 노드를 무시하는 모든 노드에서 호출됩니다. 함수가 이벤트를 소비하면 SceneTree.set_input_as_handled ()를 호출 할 수 있으며 더 이상 이벤트가 전파되지 않습니다. 이렇게하면 GUI 이전에도 관심있는 모든 이벤트를 필터링 할 수 있습니다. 게임 플레이 입력의 경우 GUI가 이벤트를 가로 채기 때문에 일반적으로 Node._unhandled_input ()이 더 적합합니다.
• Second, it will try to feed the input to the GUI, and see if any control can receive it. If so, the Control will be called via the virtual function Control._gui_input() and the signal "input_event" will be emitted (this function is re-implementable by script by inheriting from it). If the control wants to "consume" the event, it will call Control.accept_event() and the event will not spread any more. Use Control.mouse_filter property to control whether a Control is notified of mouse events via Control._gui_input() callback, and whether these events are propagated further.
  둘째, 입력을 GUI에 공급하고 어떤 컨트롤이 그것을받을 수 있는지 확인합니다. 그렇다면 Control은 가상 함수 인 Control._gui_input ()을 통해 호출되며 signal "input_event"가 출력됩니다 (이 함수는 상속을 통해 스크립트로 다시 구현할 수 있습니다). 컨트롤이 이벤트를 "소비"하려고하면 Control.accept_event ()를 호출하고 이벤트가 더 이상 전파되지 않습니다. Control.mouse_filter 속성을 사용하면 Control._gui_input () 콜백을 통해 컨트롤에 마우스 이벤트가 통보되는지 여부와 이러한 이벤트가 더 전파되는지 여부를 제어 할 수 있습니다.
• If so far no one consumed the event, the unhandled input callback will be called if overridden (and not disabled with Node.set_process_unhandled_input()). If any function consumes the event, it can call SceneTree.set_input_as_handled(), and the event will not spread any more. The unhandled input callback is ideal for full-screen gameplay events, so they are not received when a GUI is active.
  지금까지 아무도 이벤트를 소비하지 않았다면, 처리되지 않은 입력 콜백은 무시되고 Node.set_process_unhandled_input ()으로 비활성화되지 않으면 호출됩니다. 함수가 이벤트를 소비하면 SceneTree.set_input_as_handled ()를 호출 할 수 있으며 더 이상 이벤트가 전파되지 않습니다. 처리되지 않은 입력 콜백은 전체 화면 게임 플레이 이벤트에 이상적이므로 GUI가 활성화되어있을 때 수신되지 않습니다.
• If no one wanted the event so far, and a Camera is assigned to the Viewport, a ray to the physics world (in the ray direction from the click) will be cast. If this ray hits an object, it will call the CollisionObject._input_event() function in the relevant physics object (bodies receive this callback by default, but areas do not. This can be configured through Area properties).
  아무도 지금까지 이벤트를 원하지 않고 카메라가 뷰포트에 지정되면 물리 세계에 대한 광선 (클릭으로부터의 광선 방향)이 전송됩니다. 이 광선이 객체를 때리면 관련 물리 객체에서 CollisionObject._input_event () 함수를 호출합니다 (본문은 본 콜백을 기본적으로 받지만 영역은 그렇지 않습니다). 이는 영역 속성을 통해 구성 할 수 있습니다.
• Finally, if the event was unhandled, it will be passed to the next Viewport in the tree, otherwise it will be ignored.
  마지막으로 이벤트가 처리되지 않은 경우 트리의 다음 뷰포트로 전달됩니다. 그렇지 않으면 무시됩니다.

When sending events to all listening nodes within a scene, the viewport will do so in a reverse depth-first order: Starting with the node at the bottom of the scene tree, and ending at the root node:
장면 내의 모든 청취 노드에 이벤트를 전송할 때, 뷰포트는 역순으로 처리합니다: 장면 트리의 맨 아래에있는 노드에서 시작하여 루트 노드에서 끝나는:

GUI events also travel up the scene tree but, since these events target specific Controls, only direct ancestors of the targeted Control node receive the event.
GUI 이벤트 또한 장면 트리 위로 이동하지만 이러한 이벤트가 특정 컨트롤을 대상으로하므로 대상 Control 노드의 상위 조상 만 이벤트를 수신합니다.

In accordance with Godot's node-based design, this enables specialized child nodes to handle and consume particular events, while their ancestors, and ultimately the scene root, can provide more generalized behaviour if needed.
Godot의 노드 기반 설계에 따라 특수한 자식 노드는 특정 이벤트를 처리하고 소비 할 수 있으며 조상과 궁극적으로 장면 루트는 필요한 경우 더 일반적인 동작을 제공 할 수 있습니다.

Anatomy of an InputEvent

InputEvent is just a base built-in type, it does not represent anything and only contains some basic information, such as event ID (which is increased for each event), device index, etc.
InputEvent는 기본 내장형 일 뿐이며 아무 것도 나타내지 않으며 이벤트 ID (각 이벤트마다 증가하는), 장치 인덱스 등과 같은 일부 기본 정보 만 포함합니다.

There are several specialised types of InputEvent, described in the table below:
InputEvent에는 다음과 같은 특수한 유형이 있습니다:

Event	Type Index	설명
InputEvent	NONE	Empty Input Event. 빈 입력 이벤트.
InputEventKey	KEY	Contains a scancode and unicode value, as well as modifiers. 스캔 코드 및 유니 코드 값과 수정자를 포함합니다.
InputEventMouseButton	MOUSE_BUTTON	Contains click information, such as button, modifiers, etc. 버튼, 수정 자 등과 같은 클릭 정보가 포함됩니다.
InputEventMouseMotion	MOUSE_MOTION	Contains motion information, such as relative, absolute positions and speed. 상대적, 절대 위치 및 속도와 같은 동작 정보가 포함됩니다.
InputEventJoypadMotion	JOYSTICK_MOTION	Contains Joystick/Joypad analog axis information. 조이스틱/조이패드 아날로그 축 정보가 들어 있습니다.
InputEventJoypadButton	JOYSTICK_BUTTON	Contains Joystick/Joypad button information. 조이스틱 / 조이패드 버튼 정보가 들어 있습니다.
InputEventScreenTouch	SCREEN_TOUCH	Contains multi-touch press/release information. (only available on mobile devices) 멀티 터치 프레스/릴리즈 정보가 포함되어 있습니다. (휴대 기기에서만 사용 가능)
InputEventScreenDrag	SCREEN_DRAG	Contains multi-touch drag information. (only available on mobile devices) 멀티 터치 드래그 정보가 포함되어 있습니다. (휴대 기기에서만 사용 가능)
InputEventAction	SCREEN_ACTION	Contains a generic action. These events are often generated by the programmer as feedback. (more on this below) 일반 작업을 포함합니다. 이러한 이벤트는 종종 피드백으로 프로그래머에 의해 생성됩니다. (아래에서 자세히 설명)

Actions

An InputEvent may or may not represent a pre-defined action. Actions are useful because they abstract the input device when programming the game logic. This allows for:
InputEvent는 미리 정의 된 액션을 나타낼 수도 있고 나타내지 않을 수도 있습니다. 액션은 게임 로직을 프로그래밍 할 때 입력 장치를 추상화하기 때문에 유용합니다. 이것은 다음을 허용합니다 :

• The same code to work on different devices with different inputs (e.g., keyboard on PC, Joypad on console).
  다른 입력 (예 : PC의 키보드, 콘솔의 조이패드)이 다른 여러 기기에서 작동하는 동일한 코드입니다.
• Input to be reconfigured at run-time.
  런타임에서 입력을 재구성하십시오.

Actions can be created from the Project Settings menu in the Actions tab.
작업은 작업 탭의 프로젝트 설정 메뉴에서 만들 수 있습니다.

Any event has the methods InputEvent.is_action(), InputEvent.is_pressed() and InputEvent.
모든 이벤트에는 InputEvent.is_action (), InputEvent.is_pressed () 및 InputEvent 메소드가 있습니다.

Alternatively, it may be desired to supply the game back with an action from the game code (a good example of this is detecting gestures). The Input singleton has a method for this: Input.parse_input_event(). You would normally use it like this:
대안 적으로, 게임 코드에서 액션으로 게임을 다시 제공하는 것이 바람직 할 수 있습니다 (이 좋은 예는 제스처를 감지하는 것입니다). 입력 싱글 톤에는 Input.parse_input_event ()에 대한 메소드가 있습니다. 일반적으로 다음과 같이 사용합니다.

var ev = InputEventAction.new()
# set as move_left, pressed
ev.set_as_action("move_left", true)
# feedback
Input.parse_input_event(ev)

InputMap

Customizing and re-mapping input from code is often desired. If your whole workflow depends on actions, the InputMap singleton is ideal for reassigning or creating different actions at run-time. This singleton is not saved (must be modified manually) and its state is run from the project settings (project.godot). So any dynamic system of this type needs to store settings in the way the programmer best sees fit.
코드에서 입력을 사용자 정의하고 다시 매핑하는 것이 종종 필요합니다. 전체 워크 플로우가 액션에 의존하는 경우, InputMap 싱글 톤은 런타임에 다른 액션을 재 할당하거나 생성하는 데 이상적입니다. 이 싱글 톤은 저장되지 않으며 (수동으로 수정해야 함) 상태가 프로젝트 설정 (project.godot)에서 실행됩니다. 따라서이 유형의 모든 동적 시스템은 프로그래머가 가장 잘 볼 수있는 방식으로 설정을 저장해야합니다.