$input

Read controller, mouse and keyboard input.

59 natives. Read-only natives only look things up; the rest change something. Parameter types use the language's names (Types).

all_pads_are_handheld

read-only

$input.all_pads_are_handheld() -> bool

Determine if all controllers are in handheld mode

Returns bool: True if all controllers are handheld.

clear_software_keyboard

$input.clear_software_keyboard()

Clear the software keyboard buffer

detect_keyboard_layout

read-only

$input.detect_keyboard_layout() -> int

Detect the current local keyboard layout

Returns int: The keyboard layout as vlocs_keyboard_layout_t

get_analog_button_latch_threshold

$input.get_analog_button_latch_threshold(user: User, key: int) -> float

Get the analog latch threshold of the specified key.

Parameter	Type	Meaning
user	User	The user handle.
key	int	The name of the key e.g. k_key_pad_zl

Returns float: The latch threshold of the key specified

get_axis

read-only

$input.get_axis(user: User, name: int, allow_fallback_input: bool) -> float

Get the value of a controller axis.

Parameter	Type	Meaning
user	User	The user handle.
name	int	The axis to query e.g. k_key_pad_left_stick_x, k_key_pad_left_stick_y, k_key_pad_right_stick_x, k_key_pad_right_stick_y, k_key_pad_zl, k_key_pad_zr.
allow_fallback_input	bool	Whether to allow input when there is no user or no valid connection index.

Returns float: Value between -1.0 and 1.0.

get_connected_controller_count

read-only

$input.get_connected_controller_count() -> int

Get the number of controllers currently connected.

Returns int: Number of connected controllers.

get_connected_controller_count_direct

read-only

$input.get_connected_controller_count_direct() -> int

Get the number of controllers currently connected (directly from wm).

Returns int: Number of connected controllers

get_gamepad_platform_pad_id

read-only

$input.get_gamepad_platform_pad_id(gamepad: int) -> int

Gets the platform pad id for a given gamepad slot.

Parameter	Type	Meaning
gamepad	int	Gamepad index.

Returns int: The platform pad id.

get_gamepad_type

read-only

$input.get_gamepad_type(user: User) -> string

Get the string name of a user's gamepad.

Parameter	Type	Meaning
user	User	The user handle.

Returns string: Gamepad type.

get_imu_acceleration

read-only

$input.get_imu_acceleration(user: User, imu_sensor_index: int) -> vec3

Get a vec3 imu acceleration.

Parameter	Type	Meaning
user	User	The user handle.
imu_sensor_index	int	The index of the imu sensor.

Returns vec3: IMU acceleration.

get_imu_count

read-only

$input.get_imu_count(user: User) -> int

Returns the number of active imu sensors in current controller style.

Parameter	Type	Meaning
user	User	The user handle.

Returns int: Number of active touches

get_input_delay

read-only

$input.get_input_delay() -> int

Gets the number of frames of client-side input delay.

Returns int: Frame count.

get_input_text

read-only

$input.get_input_text(sanitize: bool) -> string

Gets the input text buffer used by the hidden imgui widget.

Parameter	Type	Meaning
sanitize	bool	Modifies string to prevent glyphs.

Returns string: Pointer to the buffer that stores the text wrapped in vscript string. Note that currently there is just one shared buffer in vgame_sim_state_t.

get_input_text_cursor_position

read-only

$input.get_input_text_cursor_position() -> int

Gets the input text cursor position.

Returns int: The cursor position.

get_input_text_with_cursor

read-only

$input.get_input_text_with_cursor(cursor_glyph: string, hidden_mode: int) -> string

Gets the input text buffer used by the hidden imgui widget, with cursor glyph added.

Parameter	Type	Meaning
cursor_glyph	string	The glyph tag string for cursor.
hidden_mode	int	The hidden text mode to use.

Returns string: Pointer to the buffer that stores the text wrapped in vscript string with cursor added. Note that currently there is just one shared buffer in vgame_sim_state_t.

get_joycon_style

read-only

$input.get_joycon_style(gamepad_index: int) -> int

Get an enum associated with the joycon style of a user's gamepad.

Parameter	Type	Meaning
gamepad_index	int	The gamepad index.

Returns int: Current joycon style. See vwm_joycon_style_t.

get_joycon_style_direct

read-only

$input.get_joycon_style_direct(gamepad_index: int) -> int

Get an enum associated with the joycon style of a user's gamepad (directly from wm).

Parameter	Type	Meaning
gamepad_index	int	The gamepad index.

Returns int: Current joycon style. See vwm_joycon_style_t.

get_key_type

read-only

$input.get_key_type(key: int) -> int

Get the type of the key specified.

Parameter	Type	Meaning
key	int	The name of the key e.g. k_key_pad_zl

Returns int: The type of the key specified e.g. k_vwm_key_type_gamepad_analog_button

get_keys_down

read-only

$input.get_keys_down(user: User) -> list

Get a list of keys currently held down.

Parameter	Type	Meaning
user	User	The user handle.

Returns list: List of keys (by name if possible, else number).

get_mouse_position

read-only

$input.get_mouse_position(user: User, allow_fallback_input: bool) -> vec2

Gets mouse position

Parameter	Type	Meaning
user	User	The user handle.
allow_fallback_input	bool	Whether to allow input when there is no user or no valid connection index.

Returns vec2: Mouse position in window coordinate.

get_mouse_settings_enabled

read-only

$input.get_mouse_settings_enabled() -> bool

Gets whether game elements should accept mouse inputs or not.

Returns bool: If mouse settings are enabled.

get_touch_delta

read-only

$input.get_touch_delta(user: User, finger_index: int) -> vec2

Get a vec2 touch delta in the same space as a mouse delta.

Parameter	Type	Meaning
user	User	The user handle.
finger_index	int	The index of the finger.

Returns vec2: Delta of specified touch.

get_touch_down_count

read-only

$input.get_touch_down_count(user: User) -> int

Returns the number of active touches this frame.

Parameter	Type	Meaning
user	User	The user handle.

Returns int: Number of active touches

get_touch_finger_id

read-only

$input.get_touch_finger_id(user: User, finger_index: int) -> int

Get a unique positive identifier for the given touch.

Parameter	Type	Meaning
user	User	The user handle.
finger_index	int	The index of the finger.

Returns int: Finger id of specified touch.

get_touch_position

read-only

$input.get_touch_position(user: User, finger_index: int) -> vec2

Get a vec2 touch position.

Parameter	Type	Meaning
user	User	The user handle.
finger_index	int	The index of the finger.

Returns vec2: Position of specified touch.

get_touch_pressed_count

read-only

$input.get_touch_pressed_count(user: User) -> int

Returns the number of pressed touches this frame.

Parameter	Type	Meaning
user	User	The user handle.

Returns int: Number of pressed touches

get_touch_released_count

read-only

$input.get_touch_released_count(user: User) -> int

Returns the number of released touches this frame.

Parameter	Type	Meaning
user	User	The user handle.

Returns int: Number of released touches

has_touch

read-only

$input.has_touch(user: User) -> bool

Check whether touch is supported.

Parameter	Type	Meaning
user	User	The user handle.

Returns bool: True if touch is supported.

is_gamepad_attached

read-only

$input.is_gamepad_attached(gamepad: int) -> bool

Determine if a gamepad is connected.

Parameter	Type	Meaning
gamepad	int	Gamepad index.

Returns bool: True if connected.

is_gamepad_primary_input

read-only

$input.is_gamepad_primary_input(user: User) -> bool

Returns if the given user's gamepad is active. Return false is any keyboard or mouse input is detected this frame or if there is no valid connection index. You can call `user.get_connection` to check if there is a valid connection.

Parameter	Type	Meaning
user	User	The user handle.

Returns bool: True if using gamepad, false otherwise.

is_key_down

read-only

$input.is_key_down(user: User, name: int, allow_fallback_input: bool) -> bool

Test if a key is currently held down.

Parameter	Type	Meaning
user	User	The user handle.
name	int	The name of the key e.g. k_key_pad_a.
allow_fallback_input	bool	Whether to allow input when there is no user or no valid connection index.

Returns bool: True if the key is held.

is_key_pressed

read-only

$input.is_key_pressed(user: User, name: int, allow_fallback_input: bool) -> bool

Test if a key state changed from up to down this frame.

Parameter	Type	Meaning
user	User	The user handle.
name	int	The name of the key to test e.g. k_key_pad_a.
allow_fallback_input	bool	Whether to allow input when there is no user or no valid connection index.

Returns bool: True if the key is pressed.

is_key_released

read-only

$input.is_key_released(user: User, name: int, allow_fallback_input: bool) -> bool

Test if a key state changed from down to up this frame.

Parameter	Type	Meaning
user	User	The user handle.
name	int	The name of the key to test e.g. k_key_pad_a.
allow_fallback_input	bool	Whether to allow input when there is no user or no valid connection index.

Returns bool: True if the key is released.

is_mouse_in_bounds

$input.is_mouse_in_bounds(user: User, min: vec2, max: vec2) -> bool

Returns true if mouse position is within given bounds.

Parameter	Type	Meaning
user	User	The user handle.
min	vec2	Min bounds screen position.
max	vec2	Max bounds screen position.

Returns bool: True if within given bounds, otherwise false.

is_mouse_visible

$input.is_mouse_visible() -> bool

Determine if mouse is currently visible.

Returns bool: True if the mouse is visible.

is_touch_down

read-only

$input.is_touch_down(user: User, finger_index: int) -> bool

Test if touch at given index was down this frame.

Parameter	Type	Meaning
user	User	The user handle.
finger_index	int	The index of the finger.

Returns bool: True if the touch is held.

is_touch_pressed

read-only

$input.is_touch_pressed(user: User, finger_index: int) -> bool

Test if touch at given index changed from up to down this frame.

Parameter	Type	Meaning
user	User	The user handle.
finger_index	int	The index of the finger.

Returns bool: True if the touch is pressed.

is_touch_released

read-only

$input.is_touch_released(user: User, finger_index: int) -> bool

Returns if touch at given index changed from down to up this frame.

Parameter	Type	Meaning
user	User	The user handle.
finger_index	int	The index of the finger.

Returns bool: True if the touch is released.

is_ui_mouse_active

read-only

$input.is_ui_mouse_active(user: User) -> bool

Returns true if the mouse should be active in the UI, showing the cursor and hovering / clicking.

Parameter	Type	Meaning
user	User	The user handle.

Returns bool: True if mouse is active.

lock_mouse_to_viewport

$input.lock_mouse_to_viewport(is_locked: bool)

Sets if the mouse should be contained to the viewport.

Parameter	Type	Meaning
is_locked	bool	Whether the mouse should be locked to the viewport.

print_connected_controller_styles

read-only

$input.print_connected_controller_styles()

Print out the current control style for each controller.

request_controller_count

$input.request_controller_count(desired_count: int, allow_dialog: bool, ignore_early_out: bool) -> int

Enforce a desired controller count.

Parameter	Type	Meaning
desired_count	int	Desired number of controllers.
allow_dialog	bool	Can the system pop a dialog for configuring the request.
ignore_early_out	bool	Ignore the early out check for meeting the controller count.

Returns int: Returns pending, success, or failed.

reset_gamepad_slots

$input.reset_gamepad_slots()

Resets any swapped gamepad slots back to default.

set_allowed_controller_count

$input.set_allowed_controller_count(controller_count: int, disable_handheld: bool)

Sets how many controllers are allowed to connect and if the handheld is allowed.

Parameter	Type	Meaning
controller_count	int	Number of (non-handheld) controllers allowed to connect.
disable_handheld	bool	If true, the handheld controller will not be allowed.

set_analog_button_latch_threshold

$input.set_analog_button_latch_threshold(user: User, key: int, threshold: float) -> bool

Set the analog latch threshold of the specified key.

Parameter	Type	Meaning
user	User	The user handle.
key	int	The name of the key e.g. k_key_pad_zl
threshold	float	The value to set as the threshold between 0 and 1

Returns bool: True is the threshold was set successfully

set_gamepad_primary_input

$input.set_gamepad_primary_input(user: User, is_gamepad_primary_input: bool)

Sets whether the given user's gamepad is active if there is a valid connection. You can call `user.get_connection` to check if there is a valid connection.

Parameter	Type	Meaning
user	User	The user handle.
is_gamepad_primary_input	bool	The value to set is_gamepad_primary_input to.

set_input_text

$input.set_input_text(text: string)

Set the input text buffer to a predefined string

Parameter	Type	Meaning
text	string	The text to write to input text buffer

set_joycon_mode

$input.set_joycon_mode(modes: list)

Set how joycons are interpreted.

Parameter	Type	Meaning
modes	list	List of acceptable joycon modes. See vwm_joycon_style_t.

set_left_stick_inner_dead_zone

$input.set_left_stick_inner_dead_zone(dead_zone: float)

Set the inner dead zone for gamepad left stick.

Parameter	Type	Meaning
dead_zone	float	The new dead zone value.

set_left_stick_outer_dead_zone

$input.set_left_stick_outer_dead_zone(dead_zone: float)

Set the outer dead zone for gamepad left stick.

Parameter	Type	Meaning
dead_zone	float	The new dead zone value.

set_relative_mouse_mode

$input.set_relative_mouse_mode(is_relative: bool)

Sets if the mouse is hidden and locked to the viewport.

Parameter	Type	Meaning
is_relative	bool	Whether mouse input should use relative mode.

set_right_stick_inner_dead_zone

$input.set_right_stick_inner_dead_zone(dead_zone: float)

Set the inner dead zone for gamepad right stick.

Parameter	Type	Meaning
dead_zone	float	The new dead zone value.

set_right_stick_outer_dead_zone

$input.set_right_stick_outer_dead_zone(dead_zone: float)

Set the outer dead zone for gamepad right stick.

Parameter	Type	Meaning
dead_zone	float	The new dead zone value.

set_software_keyboard_text

$input.set_software_keyboard_text(text: string)

Set the text of the software keyboard buffer.

Parameter	Type	Meaning
text	string	The new text buffer value.

show_mouse

$input.show_mouse(show: bool)

Sets if the mouse is visible.

Parameter	Type	Meaning
show	bool	Whether mouse cursor should be visible.

show_online_keyboard

$input.show_online_keyboard()

Shows software keyboard using first party network API.

software_keyboard

read-only

$input.software_keyboard(user: User, header_text: string, guide_text: string, max_length: int, hide_text: bool, numeric_only: bool) -> list

Show software keyboard this frame and get any text the user has entered.

Parameter	Type	Meaning
user	User	The user handle.
header_text	string	Title text to use for keyboard.
guide_text	string	Default value of the text entry.
max_length	int	Maximum number of characters allowed to be input.
hide_text	bool	If true, do not show text as it is entered.
numeric_only	bool	If supported by system, only allow numeric input if true.

Returns list: At index 0: Text entered if entry is complete. Otherwise null. An empty string if entry was cancelled. At index 1: Whether the entry process was aborted for any reason, for instance the user cancelled it.

swap_gamepad_slots

$input.swap_gamepad_slots(a: int, b: int)

Swap two gamepad slots so that controller A now drives the input on the second slot, and controller B the first.

Parameter	Type	Meaning
a	int	The first gamepad index.
b	int	The second gamepad index.

text

$input.text(max_length_chars: int, max_length_bytes: int, set_cursor_pos: bool, new_cursor_pos_utf8: int, hidden_mode: bool) -> string

Use hidden imgui widget to receive text input. Note that this will grab and lock imgui focus.

Parameter	Type	Meaning
max_length_chars	int	The maximum length of the string to return in user facing characters.
max_length_bytes	int	The maximum length of the string to return in byte usage (including null terminator).
set_cursor_pos	bool	If true, the text input cursor position will be changed to new_cursor_pos_utf8.
new_cursor_pos_utf8	int	The new cursor position (in utf-8 character index) to set to
hidden_mode	bool	If true, text input will be hidden.

Returns string: Pointer to the buffer that stores the text wrapped in vscript string for display. Note that currently there is just one shared buffer in vgame_sim_state_t.