|
| 1 | +# Input |
| 2 | + |
| 3 | +## `app.control(options)`: Control |
| 4 | + |
| 5 | +The `app.control()` method gives you access to user inputs like keyboard and mouse and gives you control over the camera etc. It's the primary way to create interactive experiences. |
| 6 | + |
| 7 | +```javascript |
| 8 | +// Get a control object |
| 9 | +const control = app.control() |
| 10 | + |
| 11 | +// The app will be cleaned up automatically, but if you need to manually release control: |
| 12 | +control.release() |
| 13 | +``` |
| 14 | + |
| 15 | +### Buttons |
| 16 | + |
| 17 | +Listen to press and release events for keyboard keys and mouse buttons. |
| 18 | + |
| 19 | +```javascript |
| 20 | +// Listen for 'W' key press and release |
| 21 | +control.keyW.onPress = () => { console.log('W pressed') } |
| 22 | +control.keyW.onRelease = () => { console.log('W released') } |
| 23 | + |
| 24 | +// Listen for left mouse button |
| 25 | +control.mouseLeft.onPress = () => { console.log('Left mouse button pressed') } |
| 26 | +``` |
| 27 | + |
| 28 | +Each button object has the following properties: |
| 29 | +* `onPress` (Function): Callback for when the button is first pressed down. |
| 30 | +* `onRelease` (Function): Callback for when the button is released. |
| 31 | +* `down` (Boolean): `true` if the button is currently held down. |
| 32 | +* `pressed` (Boolean): `true` for the single frame when the button is first pressed. |
| 33 | +* `released` (Boolean): `true` for the single frame when the button is released. |
| 34 | +* `capture` (Boolean): If set to `true`, it will consume the event and prevent lower-priority controls from receiving it. |
| 35 | + |
| 36 | +Here is a list of available button properties: |
| 37 | + |
| 38 | +`keyA` to `keyZ`, `digit0` to `digit9`, `minus`, `equal`, `bracketLeft`, `bracketRight`, `backslash`, `semicolon`, `quote`, `backquote`, `comma`, `period`, `slash`, `arrowUp`, `arrowDown`, `arrowLeft`, `arrowRight`, `home`, `end`, `pageUp`, `pageDown`, `tab`, `capsLock`, `shiftLeft`, `shiftRight`, `controlLeft`, `controlRight`, `altLeft`, `altRight`, `enter`, `space`, `backspace`, `delete`, `escape`, `mouseLeft`, `mouseRight`, `metaLeft`. |
| 39 | + |
| 40 | +### Pointer |
| 41 | + |
| 42 | +Access pointer (mouse) information. |
| 43 | + |
| 44 | +```javascript |
| 45 | +// Get pointer delta every frame |
| 46 | +app.on('update', () => { |
| 47 | + const pointerDelta = control.pointer.delta |
| 48 | + if (pointerDelta.x !== 0 || pointerDelta.y !== 0) { |
| 49 | + console.log('Pointer moved:', pointerDelta.x, pointerDelta.y) |
| 50 | + } |
| 51 | +}) |
| 52 | +``` |
| 53 | + |
| 54 | +* `pointer.coords` (Vector3): Pointer coordinates in normalized screen space (`[0,0]` to `[1,1]`). |
| 55 | +* `pointer.position` (Vector3): Pointer coordinates in screen pixels. |
| 56 | +* `pointer.delta` (Vector3): Change in pointer position since the last frame. |
| 57 | +* `pointer.locked` (Boolean): `true` if the pointer is currently locked. |
| 58 | +* `pointer.lock()`: Requests to lock the pointer to the screen. |
| 59 | +* `pointer.unlock()`: Releases the pointer lock. |
| 60 | + |
| 61 | +### Scroll |
| 62 | + |
| 63 | +Get mouse scroll wheel changes. |
| 64 | + |
| 65 | +```javascript |
| 66 | +// The value is the scroll delta for the current frame. |
| 67 | +const scrollDelta = control.scrollDelta.value |
| 68 | +``` |
| 69 | + |
| 70 | +* `scrollDelta.value` (Number): The scroll delta for the current frame. |
| 71 | +* `scrollDelta.capture` (Boolean): If `true`, consumes the scroll event. |
| 72 | + |
| 73 | +### Camera |
| 74 | + |
| 75 | +Lets you read and also modify the camera position if needed. |
| 76 | + |
| 77 | +By default the camera information is read-only, set `write` to true when you want to take over control. |
| 78 | + |
| 79 | +```jsx |
| 80 | +control.camera.write = true |
| 81 | +control.camera.position.y = 4 |
| 82 | +``` |
| 83 | + |
| 84 | +* `camera.position` (Vector3): The position of the camera in world space. |
| 85 | +* `camera.quaternion` (Quaternion): The quaternion rotation of the camera in world space. |
| 86 | +* `camera.rotation` (Euler): The euler rotation (radians) of the camera in world space. |
| 87 | +* `camera.zoom` (Number): Third person zoom value, eg how far back the camera is from its position. |
| 88 | +* `camera.write` (Boolean): Set this to `true` if you want to modify the camera in any way. |
| 89 | + |
| 90 | + |
| 91 | +### Screen |
| 92 | + |
| 93 | +Gives you the dimensions of the screen in pixels, useful when positioning UI. |
| 94 | + |
| 95 | +* `screen.width` (Number): The width of the screen in px. |
| 96 | +* `screen.height` (Number): The height of the screen in px. |
0 commit comments