Skip to content

Commit 88dff4c

Browse files
suearkinunitysuearkinunity
committed
Replacing diagrams
1 parent 72d48e7 commit 88dff4c

1 file changed

Lines changed: 150 additions & 2 deletions

File tree

‎Packages/com.unity.inputsystem/Documentation~/Architecture.md‎

Lines changed: 150 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,76 @@ The Input System can also send data back to the native backend in the form of [c
1515

1616
# Input System (low-level)
1717

18-
![Low-Level Architecture](Images/InputArchitectureLowLevel.png)
18+
The diagram below reads top-to-bottom as a layered pipeline: the native **platform backends** at the bottom feed the **InputManager**, which uses **layouts** to build **devices** whose state is stored in **Input State Memory** at the top.
19+
20+
```mermaid
21+
flowchart TB
22+
%% ---------- Input State Memory (top) ----------
23+
StateMemory["Input State Memory
24+
(unmanaged raw memory — each device and control
25+
gets a chunk that stores its current state)"]
26+
27+
%% ---------- Devices (built from layouts) ----------
28+
Gamepad_D["Gamepad (device)"] --> leftStick
29+
leftStick --> x & y & up & down & left & right
30+
Keyboard_D["Keyboard (device)"] --> a & b & c & d
31+
leftStick -->|"state written to"| StateMemory
32+
Keyboard_D -->|"state written to"| StateMemory
33+
34+
%% ---------- Layouts (describe how to build controls and devices) ----------
35+
Mouse -->|derives| Pointer
36+
Pen -->|derives| Pointer
37+
Touchscreen -->|derives| Pointer
38+
DS_PS4["DualShock (PS4)"] --> DualShock
39+
DS_HID["DualShock (HID)"] --> DualShock
40+
DualShock --> Gamepad_L["Gamepad (layout)"]
41+
Keyboard_L["Keyboard (layout)"]
42+
Stick(("Stick"))
43+
Axis(("Axis"))
44+
Button(("Button"))
45+
Dpad(("Dpad"))
46+
47+
%% Layout building blocks build the individual device controls
48+
Gamepad_L -.->|builds| Gamepad_D
49+
Stick -.->|builds| leftStick
50+
Axis -.->|builds| x & y
51+
Button -.->|builds| up & down & left & right
52+
Keyboard_L -.->|builds| Keyboard_D
53+
54+
%% ---------- InputManager (middle) ----------
55+
InputManager(["<b>InputManager</b>
56+
Matches layouts to devices (InputDeviceMatcher),
57+
builds devices (InputDeviceBuilder), creates & updates them"])
58+
Gamepad_L -->|"searched by"| InputManager
59+
InputManager -->|"creates & updates"| Gamepad_D
60+
InputManager -->|"creates & updates"| Keyboard_D
61+
62+
%% ---------- Input Runtime (bottom) ----------
63+
DDQ["Device Discovery Queue"]
64+
EQ["Event Queue"]
65+
BEQ["Background Event Queue
66+
(async; flushes into the foreground queue)"]
67+
Backends["Platform Backends
68+
Windows · macOS · Linux · UWP · iOS · Android
69+
· Switch · Xbox · PS4 · WebGL · XR"]
70+
Backends --> DDQ & EQ & BEQ
71+
DDQ -->|"Device Discovered"| InputManager
72+
EQ -->|"Update (flushes event buffers)"| InputManager
73+
InputManager -->|"Queue Event"| EQ
74+
InputManager -->|"Device Command (IOCTL-style)"| Backends
75+
76+
%% ---------- Grouping by color ----------
77+
classDef layout fill:#e6f0ff,stroke:#4a78c0,color:#000;
78+
classDef device fill:#e8f7e8,stroke:#4aa04a,color:#000;
79+
classDef runtime fill:#fdf3d0,stroke:#b9962e,color:#000;
80+
classDef mem fill:#f0e6f6,stroke:#8a5ea0,color:#000;
81+
classDef manager fill:#ffffff,stroke:#e0403f,stroke-width:2px,color:#000;
82+
class Mouse,Pen,Touchscreen,Pointer,DS_PS4,DS_HID,DualShock,Gamepad_L,Keyboard_L,Stick,Axis,Button,Dpad layout;
83+
class Gamepad_D,leftStick,x,y,up,down,left,right,Keyboard_D,a,b,c,d device;
84+
class DDQ,EQ,BEQ,Backends runtime;
85+
class StateMemory mem;
86+
class InputManager manager;
87+
```
1988

2089
The low-level Input System code processes and interprets the memory from the event stream that the native backend provides, and dispatches individual events.
2190

@@ -25,7 +94,86 @@ The low-level system code also contains structs which describe the data layout o
2594

2695
# Input System (high-level)
2796

28-
![High-Level Architecture](Images/InputArchitectureHighLevel.png)
97+
The high-level system is easiest to understand in two parts: how input flows through the system at **runtime**, and how Actions are **authored as assets**. Both are shown below for a single player; each additional player gets its own `InputActionState` and a cloned `InputActionAsset` with its own device list and binding mask.
98+
99+
**Runtime data flow** — a Device control's state is written into Input State memory, a State Change Monitor notices the change, the `InputActionState` is updated, and the resulting Action fires a callback on the `PlayerInput` component in the scene:
100+
101+
```mermaid
102+
flowchart LR
103+
%% ---------- Devices ----------
104+
Keyboard["Keyboard"] --> space["space"]
105+
106+
%% ---------- Input State (unmanaged raw memory) ----------
107+
KBbit["KeyboardState
108+
1 Bit for Space Key"]
109+
space -->|"stored in"| KBbit
110+
111+
%% ---------- Runtime ----------
112+
StateEvent["StateEvent (KeyboardState)
113+
NativeInputSystem.onUpdate"] -->|feeds| OnUpdate["InputManager.OnUpdate()"]
114+
115+
%% ---------- Action state ----------
116+
AState(["InputActionState
117+
NotifyControlStateChanged()"])
118+
trig["triggerStates[]"]
119+
bind["bindingStates[]"]
120+
ctrl["controls[]"]
121+
AState --> trig & bind & ctrl
122+
OnUpdate ==>|"NotifyControlStateChanged()"| AState
123+
KBbit -->|"State Change Monitor"| bind
124+
space -->|"State Change Monitor"| ctrl
125+
126+
%% ---------- Callback out to the scene ----------
127+
trig -->|triggers| IU["InputUser"]
128+
IU -->|"OnActionTriggered()"| PI["PlayerInput
129+
(Scene GameObject)"]
130+
131+
classDef device fill:#e6f0ff,stroke:#4a78c0,color:#000;
132+
classDef state fill:#cfcfcf,stroke:#555,color:#000;
133+
classDef astate fill:#efe9ff,stroke:#7a5ec0,color:#000;
134+
classDef runtime fill:#fdf3d0,stroke:#b9962e,color:#000;
135+
classDef go fill:#d9d9d9,stroke:#666,color:#000;
136+
class Keyboard,space device;
137+
class KBbit state;
138+
class AState,trig,bind,ctrl astate;
139+
class StateEvent,OnUpdate runtime;
140+
class IU,PI go;
141+
```
142+
143+
**Asset structure** — an `InputActionAsset` contains Maps, Actions, and Bindings. At runtime these populate the arrays inside the `InputActionState` shown above (`m_State`):
144+
145+
```mermaid
146+
flowchart LR
147+
%% ---------- Asset hierarchy ----------
148+
Asset["InputActionAsset: MyGame.inputactions
149+
devices = [ Keyboard ]
150+
bindingMask = { groups: KeyboardMouse }"]
151+
Map["InputActionMap: gameplay"]
152+
Act["InputAction (m_Actions[])
153+
gameplay/jump"]
154+
Bind_a["InputBinding (m_Bindings[])
155+
path: &lt;Keyboard&gt;/space
156+
action: jump — groups: KeyboardMouse"]
157+
Bind_b["InputBinding (m_Bindings[])
158+
path: &lt;Gamepad&gt;/buttonSouth
159+
action: jump — groups: Gamepad"]
160+
Asset --> Map
161+
Map --> Act
162+
Map --> Bind_a & Bind_b
163+
164+
%% ---------- Populates the runtime action state ----------
165+
Act -.->|populates| trig["triggerStates[]"]
166+
Bind_a -.->|populates| bind["bindingStates[]"]
167+
Bind_b -.->|populates| bind
168+
bind -.->|resolves controls| ctrl["controls[]"]
169+
State(["InputActionState
170+
(m_State)"]) --- trig & bind & ctrl
171+
172+
classDef asset fill:#e8f7e8,stroke:#4aa04a,color:#000;
173+
classDef astate fill:#efe9ff,stroke:#7a5ec0,color:#000;
174+
class Asset,Map,Act,Bind_a,Bind_b asset;
175+
class trig,bind,ctrl,State astate;
176+
```
29177

30178
The high-level Input System code interprets the data in a Device's state buffers by using [layouts](layouts.md), which describe the data layout of a Device and its Controls in memory. The Input System creates layouts from either the pre-defined structs of commonly known Devices supplied by the low level system, or dynamically at runtime, as in the case of [generic HIDs](hid-specification.md).
31179

0 commit comments

Comments
 (0)